Using eformsign Webhook

This is a feature that sends event information to the customer’s system/service when an event occurs in eformsign. By configuring Webhook, event information is sent to the customer’s webhook endpoint in the HTTP POST method.

Tip

A Webhook endpoint refers to the customer’s client callback URL. It allows you to get eformsign event information without making unnecessary calls, which differs from the Open API method where calls are continuously made to check for changes (polling).

Getting started

Getting a Webhook key

  1. Log in to eformsign as the company administrator and then go to [Integration] > [API / Webhook] in the sidebar menu.

Integration > API/Webhook menu
  1. Select the [Manage Webhook] tab and then click the New Webhook button.

New Webhook button
  1. In the New Webhook pop-up, enter the Name, URL, and the List of affected templates, and make sure that the status is in enabled status. Then, click the Register button.

New Webhook pop-up
  1. Click the View key button in the Webhook list to view the Webhook public key.

Webhook View key button View key

Caution

If you click the Regenerate key button, the Webhook public key will be issued to you again and you will not be able to use the previous key.

Note

Editing Webhook information

You can change the information of a Webhook by clicking the Edit button in the Webhook list.

Note

Deleting a Webhook

You can delete a Webhook by clicking the Delete button in the Webhook list.

  1. Click the Test button in the Webhook list to send a test Webhook and get the returned results.

Webhook Test

The following is a json file used for testing purposes.

{
"webhook_id" : "Webhook ID",
"webhook_name" : "Webhook name",
"company_id" : "company ID",
"event_type" : “document”,
"document" : {
  "id" : “test_doc_id”,
   "template_id" : “test_template_id”,
   "template_version" : “1”,
   "document_history_id" : “test_document_history_id”,
   "doc_status" : “doc_create”,
   "editor_id" : "user ID",
   "updated_date" : "current time(UTC Long)"
}
}
Test URL : Webhook URL

Generating a signature

The following describes how to generate a signature for each language: Java, Python, and PHP.

Java

Check the event information received from the eformsign server by using the public key issued to you in Getting a Webhook Key to verify whether the event was called normally from eformsign.

Note

The signature algorithm used is SHA256withECDSA.

Python

Use the library for key generation in the link below. Install the library using the following command.

pip install https://github.com/warner/python-ecdsa/archive/master.zip

PHP

Make sure that the keycheck.inc.php and test.php files in the following examples are located in the same path before proceeding.

Examples

The following shows the examples for each language.

import java.io.*;
        import java.math.BigInteger;
        import java.security.*;
        import java.security.spec.X509EncodedKeySpec;

        ....
        /**
         *  Reads the header and body in the request.
         *
         */


        //1. get eformsign signature
        //eformsignSignature is contained in the request header.
        String eformsignSignature = request.getHeader("eformsign_signature");


        //2. get request body data
        // Converts the data in the body to string to verify the eformsign signature.
        String eformsignEventBody = null;
        StringBuilder stringBuilder = new StringBuilder();
        BufferedReader bufferedReader = null;

        try {
            InputStream inputStream = request.getInputStream();
            if (inputStream != null) {
                bufferedReader = new BufferedReader(new InputStreamReader(inputStream));
                char[] charBuffer = new char[128];
                int bytesRead = -1;
                while ((bytesRead = bufferedReader.read(charBuffer)) > 0) {
                    stringBuilder.append(charBuffer, 0, bytesRead);
                }
            }
         } catch (IOException ex) {
            throw ex;
         } finally {
            if (bufferedReader != null) {
                try {
                    bufferedReader.close();
                } catch (IOException ex) {
                    throw ex;
                }
            }
         }
        eformsignEventBody = stringBuilder.toString();




        //3. publicKey configuration
        String publicKeyHex = "the issued Public Key(String)";
        KeyFactory publicKeyFact = KeyFactory.getInstance("EC");
        X509EncodedKeySpec x509KeySpec = new X509EncodedKeySpec(new BigInteger(publicKeyHex,16).toByteArray());
        PublicKey publicKey = publicKeyFact.generatePublic(x509KeySpec);

        //4. verify
        Signature signature = Signature.getInstance("SHA256withECDSA");
        signature.initVerify(publicKey);
        signature.update(eformsignEventBody.getBytes("UTF-8"));
        if(signature.verify(new BigInteger(eformsignSignature,16).toByteArray())){
            //verify success
            System.out.println("verify success");
            /*
             *Events are handled here.
             */
        }else{
            //verify fail
            System.out.println("verify fail");
        }
import hashlib
                import binascii

        from ecdsa import VerifyingKey, BadSignatureError
        from ecdsa.util import sigencode_der, sigdecode_der
        from flask import request


        ...
        # Reads the header and boy in the request.
        # 1. get eformsign signature
        # eformsignSignature is contained in the request header.
    eformsign_signature_str= request.headers['eformsign_signature']
    eformsign_signature = binascii.unhexlify(eformsign_signature_str)


        # 2. get request body data
        # Converts the data in the body to string to verify the eformsign signature.
        data = request.data


        # 3. publicKey configuration
        publicKeyHex = "the issued public key"
        publickey = VerifyingKey.from_der(binascii.unhexlify(publicKeyHex))


        # 4. verify
        try:
            if publickey.verify(eformsign_signature, data, hashfunc=hashlib.sha256, sigdecode=sigdecode_der):
                print("verify success")
                # Events are handled here.
        except BadSignatureError:
            print("verify fail")
<?php
namespace eformsignECDSA;

class PublicKey
{

    function __construct($str)
    {
        $pem_data = base64_encode(hex2bin($str));
        $offset = 0;
        $pem = "-----BEGIN PUBLIC KEY-----\n";
        while ($offset < strlen($pem_data)) {
            $pem = $pem . substr($pem_data, $offset, 64) . "\n";
            $offset = $offset + 64;
        }
        $pem = $pem . "-----END PUBLIC KEY-----\n";
        $this->openSslPublicKey = openssl_get_publickey($pem);
    }
}

function Verify($message, $signature, $publicKey)
{
    return openssl_verify($message, $signature, $publicKey->openSslPublicKey, OPENSSL_ALGO_SHA256);
}
?>
<?php
require_once __DIR__ . '/keycheck.inc.php';
use eformsignECDSA\PublicKey;

define('PUBLIC_KEY', 'input the issued public key.');
...
/*
 *  Reads the header and body in the request.
 *
 */


//1. get eformsign signature
//eformsignSignature is contained in the request header.
$eformsignSignature = $_SERVER['HTTP_eformsign_signature'];


//2. get request body data
// Reads the data in the body to verify the eformsign signature.
$eformsignEventBody = json_decode(file_get_contents('php://input'), true);


//3. publicKey configuration
$publicKey = new PublicKey(PUBLIC_KEY);


//4. verify
$ret = - 1;
$ret = eformsignECDSA\Verify(MESSAGE, $eformsignSignature, $publicKey);

if ($ret == 1) {
    print 'verify success' . PHP_EOL;
    /*
     * Events are handled here.
     */
} else {
    print 'verify fail' . PHP_EOL;
}
 ...

?>

Webhook list

By configuring the following Webhook, you can receive the information in the webhook endpoint when the configured event occurs in eformsign.

The following is Webhook provided in eformsign.

POST: /webhook document event Send Webhook

Click here for more information about each eformsign Webhook.

Webhook events

eformsign provides document events and PDF generation events as Webhook events.

Document events

This event occurs when a document is created or the status of a document is changed in eformsign.

Name

Type

Description

id

String

Document ID

template_id

String

Template ID

template_name

String

Template name

template_version

String

Template title

workflow_seq

int

Workflow order

workflow_name

String

Workflow name

history_id

String

Document history ID

status

String

Document status

editor_id

String

Creator ID

updated_date

long

Document update time

Refer to the following for the meaning of each document status in event data.

Name

Description

doc_create

Document created

doc_tempsave

Document saved as a draft

doc_request_approval

Document approval requested

doc_accept_approval

Document approval request approved

doc_reject_approval

Document approval request declined

doc_request_external

Document sent to external recipient

doc_remind_external

Document resent to external recipient

doc_open_external

Document opened by external recipient

doc_accept_external

Document reviewed by external recipient

doc_reject_external

Document declined by external recipient

doc_request_internal

Document sent to internal recipient

doc_accept_internal

Document reviewed by internal recipient

doc_reject_internal

Document declined by internal recipient

doc_tempsave_internal

Document saved as a draft by internal recipient

doc_cancel_request

Document approval request cancelled

doc_reject_request

Document requested to be declined

doc_decline_cancel_request

Document decline request rejected

doc_delete_request

Document requested to be deleted

doc_decline_delete_request

Document deletion request rejected

doc_deleted

Document deleted

doc_complete

Document completed

PDF generation events

The following is a list of events generated when the PDF file of a document is created in eformsign.

Name

Type

Description

document_id

String

Document ID

template_id

String

Template ID

template_name

String

Template name

template_version

String

Template title

workflow_seq

int

Workflow order

workflow_name

String

Workflow name

document_history_id

String

Document history ID

document_status

String

Document status

For the meaning of each document status in event data, refer to the document status section.