Now before I jump into the callback let me tell you something about HelloSign.

Pic Courtesy:

HelloSign is a paid (For testing free services are provided) tool for digital/online signing of the documents and they are the currently the best option at implementing it . There are other options available to you as well such as –

  1. DocHub.
  2. DocuSign.
  3. Etc…Just google it!!!

both of the above mentioned lack their own Integration Api ,Also they don’t have many functionality at implementing which HelloSign has.

Anyway this is not promotional blog for HelloSign ,So it’s up to you but I used it in one of our projects for digital signing of documents and to get more information about it you can go through the link here: .

And If you want to integrate HelloSign API in your site or have already started it ,I will go step by step using their nodeJs module ‘hellosign-sdk’  and then tell you exactly what problem I faced during callback implementation and there documentation also did not helped as they have written the useful information in docs maybe in very small font or burdened the useful info under a lot of unnecessary information or just haven’t written about it.

 Here are the steps-

  • First step, Get your API key .I will be using a Test API key which you can also get just after signing up to the site( ), you can generate your own by going into your HelloSign Account settings.












  • Next step, install the ‘hellosign-sdk’ npm module( in your node application and create a endpoint for sending a signing request.
    Example Endpoint: ‘http://localhost/api/tours/sign_request’ .The following code is used with dummy data using their Test API.

    export function helloSign_setSignature(req, res){
    var options = {
        test_mode : 1,
        title : 'Test Title.',
        subject : 'Digital Signature: Risk and Release form',
        message : 'Please sign this form and then we can discuss more.',
        signers : [
                email_address : '',
                name : 'KK',
                order : 0
        cc_email_addresses : [''],
        files : ['Sample - Itinerary.pdf'],
        metadata : {
            clientId : '1234',
            custom_text : 'NDA #9'
    //parse response
            //catch error

    By hitting the above endpoint you will send the Signing Request to the Signer’s email address.

  • The next point is now to listen to the request send out for signing documents .Now ,polling API is an option on fixed interval but its not the right way as it will keep lot of your useful resources busy and the HelloSign Team has also suggested not to do that. Hence ,they have provided something as ‘WebHook’ .Just like we have used hooks in various condition where we wanted to do something right after or before some event in our application level ,Similarly they have provided webhook where you can just hook one of the callback urls to your HelloSign account and anytime a signing Request event happens which is related to your account it will hit the callback provided.Now ,here’s the catch in their documentation they have in the next point.


  • This is the code I have written for the callback in nodejs .
    export function helloSign_callback(req, res,json){
    Var data = req.body.json;
    console.log(“Input payload of the event-----”,data);
    res.status(200).send('Hello API Event Received');

    The code looks fine and simple ,Right ..? you just add the endpoint to the API callback in your account settings of HelloSign.

    NOTE: HelloSign API callback requires response body to be ‘Hello API Event Received’ with 200 status code.















  • The catch here is the above callback will work but you won’t get the Event payload data which I have
    printed to console.Why…..? we have done everything right..!!! The payload according to their docs should be in “json” named param but you will get ‘Undefined’.


    Now ,The catch here is that the default format for messages sent to you callbacks is a multipart(‘form/multipart’’) 
    POST request, with the message details in a POST field named ‘json’.So, the above format multipart(‘form/multipart’’) is basically used for uploading documents.
    Therefore we have to use some way to parse it as array, In nodejs we have a NPM module named ‘multer’ that has to be used as middleware to the endpoint so that we get the payload in the req.body.json as text/string.Next we can easily parse it as json for further use that we have to do with the event data.


    Here is the code for that:

    export function helloSign_callback(req, res,json){
        var data = req.body.json;
        data = JSON.parse(data);
        data = data.event;
        console.log(“Input payload of the event-----”,data);
        var apiKey = 'USE THE TESTING API KEY';
        var calculate_hash = crypto.createHmac('sha256', apiKey).update(data.event_time + data.event_type).digest('hex').toString();
        var event_hash = data.event_hash;
            res.status(200).send('Hello API Event Received');

    Also ,we will have to add  .array() method of multer to the Endpoint Route.

    var app = express();
    var multer  = require('multer');
    var upload = multer();'/api/tours/hellosign_callback', upload.array(),helloSign_callback);
    //use array or single or fields method of multer module for handling text only multipart field...







  • Another catch here is you cannot test the API callback for Endpoints referring to your LOCALHOST development environment. For Example: http://localhost/api/tours/sign_request, this they have mentioned in their docs as well.So you will have to use something like ngrok or localtunnel or pagekite or something else which will be providing tunneling or the port forwarding service.

    So if you have any problems while integration  ,just go through these points and your problem might will get resolved.

Looking for Node.js Development Company, Hire our dedicated developers!

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

This site uses Akismet to reduce spam. Learn how your comment data is processed.