The Adobe Sign Webhook feature is available to Enterprise accounts with the API enabled.

Feature description

webhook is a user-defined HTTPS callback that is triggered when a particular event occurs at the source site (Adobe Sign in this case).

Effectively, a webhook is nothing butweb service that accepts HTTPS POST requests from a source. So, a webhook is a REST service that accepts data or a stream of data.

Webhooks are for service to service communication in a Push model.

When a trigger event occurs, Adobe Sign constructs an HTTPS POST with a JSON body, and delivers that to the URL specified.

 

Webhooks offer multiple benefits over the previous Callback method, some of which are:

  • Admins can enable their own webhooks without having to involve Adobe Sign support to list the callback URL
  • Webhooks are better in terms of data "freshness", efficiency of communication, and security. No polling required
  • Webhooks allow for different levels of scope (Account/Group/User/Resource) easily. 
  • Webhooks are a more modern API solution, allowing for easier configuration to modern applications
  • Multiple webhooks can be configured per scope (Account/Group/User/Resource), where Callbacks were required to be unique
  • Webhooks allow for selection of the data to be returned, where Callbacks are an "all or nothing" solution
  • Metadata carried with a webhook can be configured (Basic or Detailed)
  • Webhooks are far easier to create, edit, or disable as needed since the UI is entirely within the control of the admin.

Hinweis:

This document is primarily focused on the Webhooks UI in the Adobe Sign web application.

Developers that are looking for API details can find more information here:


How it's used

Admins will first need to have a webhook service, ready to accept the inbound push from Adobe Sign. There are many options in this regard, and as long as the service can accept POST and GET requests, the webhook will be successful.

Once the service is in place, an Adobe Sign admin can create a new webhook from the Webhook interface in the Account menu of the Adobe Sign site.

Admins can configure the webhook to trigger for Agreement, Widget, or Mega Sign events.

The scope of the webhook can include the whole account or individual groups through the admin interface. User and Resource scopes are also possible through the API

They type of data that is pushed to the URL is configurable, and can include things like the Agreement Info, Participant Info, the Signed Document, and so on.

Once the webhook is configured and saved, Adobe Sign will push a new JSON object to the defined URL every time the trigger event is trapped. No ongoing manipulation of the webhook is required unless you want to change the event trigger criteria, or the JSON payload.


Verification of intent of the webhook URL

Before registering a webhook successfully, Adobe Sign verifies that the webhook URL that is provided in the registration request, really intends to receive notifications or not. For this purpose, when a new webhook registration request is received by Adobe Sign, it first makes a verification request to the webhook URL. This verification request is an HTTPS GET request sent to the webhook URL with a custom HTTP header X-AdobeSign-ClientId. The value in this header is set to the client ID of the application that is requesting to create/register the webhook. To successfully register a webhook, the webhook URL must respond to this verification request with a 2XX response code AND additionally it must send back the same client id value in one of the following two ways.

  • Either in a response header X-AdobeSign-ClientId. This is the same header which was passed in the request, and be echoed back in the response.
  • Or in the JSON response body with the key of xAdobeSignClientId and its value being the same client ID that was sent in the request.

The webhook will be successfully registered only on a success response(2XX response code) and validation of client id either in header or response body. The purpose of this verification request is to demonstrate that your webhook URL really does want to receive notifications at that URL. If you accidentally entered the wrong URL, the URL would fail to respond correctly to the verification of intent request, and Adobe Sign will not send any notifications to that URL. Additionally, the webhook URL can also validate that it would receive notifications only through the webhooks which are registered by a specific application. This can be done by validating the client ID of the application passed in the X-AdobeSign-ClientId header. If the webhook URL does not recognize that client id, it MUST NOT respond with the success response code and Adobe Sign will take care that the URL is not registered as a webhook.

The verification of webhook URL call will be made in the following scenarios:

  • Registering Webhook: If this verification of webhook URL call fails, the webhook will not be created.
  • Updating Webhook: INACTIVE to ACTIVE: If this verification of webhook URL call fails, the webhook state will not be changed to ACTIVE.

Additionally, we perform an implicit verification of intent in each webhook notification request that we send to the webhook URL. Thus, every notification request will also include a header called X-AdobeSign-ClientId that includes client id of the application that created the webhook. We will consider the webhook notification successfully delivered, if an only if success response (2XX response code) is returned and the header (X-AdobeSign-ClientId) is echoed back in response HTTP header or in a JSON response body with key as xAdobeSignClientId and value as the same client id, otherwise we will retry to deliver the notification to the webhook URL until the retries are exhausted.

Sample code to respond to a webhook verification & notification

As mentioned above, the header 'X-AdobeSign-ClientId' which is included in every notification request from Sign, the value of this header(client id)  should be echoed back in response in either of two ways:

1. HTTP header X-AdobeSign-ClientId and value as this client id

Sample Javascript code to to fetch the client id, validate it, and then return it in the response header

// Fetch client id

var clientid = request.headers['X-ADOBESIGN-CLIENTID'];

 

//Validate it

if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

    //Return it in response header

    response.headers['X-AdobeSign-ClientId'] = clientid;

    response.status = 200;  // default value

}

Sample PHP code to to fetch the client id, validate it, and then return it in the response header

 

<?php

// Fetch client id

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Validate it

if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

    //Return it in response header

   header("X-AdobeSign-ClientId:$clientid");

   header("HTTP/1.1 200 OK"); // default value

}

?>

 


2. JSON response body with key as xAdobeSignClientId and value as the same client id

Sample Javascript code to to fetch the client id, validate it, and return it in the response body

// Fetch client id

var clientid = request.headers['X-ADOBESIGN-CLIENTID'];

 

 

//Validate it

if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

    var responseBody = {

                         "xAdobeSignClientId" : clientid // Return Client Id in the body

                       };

    response.headers['Content-Type'] = 'application/json';

    response.body = responseBody;

    response.status = 200;

}

Sample PHP code to to fetch the client id, validate it, and return it in the response body

<?php

// Fetch client id

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Validate it

if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

   //Return it in response body

   header("Content-Type: application/json");

   $body = array('xAdobeSignClientId' => $clientid);

   echo json_encode($body);

   header("HTTP/1.1 200 OK"); // default value

}

?>

Sample JSON body of the response

{

    "xAdobeSignClientId": "BGBQIIE7H253K6"

}

Using "Azure Functions" to create an Adobe Sign webhook

Prerequisites

You will need:

  1. A Microsoft account with license to create Azure Functions Applications
  2. An existing Azure Function Application, you can create one using https://docs.microsoft.com/en-us/azure/azure-functions/functions-create-first-azure-function 
  3. Basic knowledge of Javascript, so that you can understand and write the code in any language of your choice


Steps to create an Azure Functions Trigger that serves as an Adobe Sign webhook

To create a Javascript HTTP Trigger function:

1. Login via you Microsoft account https://portal.azure.com/

2. Open you Azure Function Application displayed under Function Apps tab.

azure_menu

This will open your list of Azure Function Applications:

3. Choose the application where in you want to create this new function

4. Click on the Create (+) button to create a new Azure function

azure_create

 

5. Select Webhook + API as the scenario and Javascript as the language

6. Click Create this function

A new function that has the capability of handling an incoming API request is created.


Add logic to register Adobe Sign webhook

Before registering a webhook successfully, Adobe Sign verifies that the webhook URL that is provided in the registration request, really intends to receive notifications or not. For this purpose, when a new webhook registration request is received by Adobe Sign, it first makes a verification request to the webhook URL. This verification request is an HTTPS GET request sent to the webhook URL with a custom HTTP header X-AdobeSign-ClientId. The value in this header is set to the client ID of the application that is requesting to create/register the webhook. To successfully register a webhook, the webhook URL must respond to this verification request with a 2XX response code AND additionally it must send back the same client id value in one of the following two ways.

There are two options you can follow:


Option 1: Pass Client Id in X-AdobeSign-ClientId as response Header

Pass X-AdobeSign-ClientId in the response header. This is the same header which was passed in the request, and must be echoed back in the response.

Replace the Index.js file with the following:

azure_case_1

module.exports = function (context, req) {

    var clientId = req.headers['x-adobesign-clientid'];

    // Validate that the incoming ClientID is genuine

    if (clientId === '123XXX456') {

        context.res = {

            // status: 200, /* Defaults to 200 */ // any 2XX response is acceptable

            body: "Notification Accepted",

            headers : {

                'x-adobesign-clientid' : req.headers['x-adobesign-clientid']

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Opps!! Illegitimate Call identified"

        };

    }

    context.done();

};

 

Test the behavior by mocking the request:

1. Click on the Test button at extreme right corner

2. Mock the dummy request

azure_case_1_test

Although response headers are not shown above but you can observe it via mocking it by postman/DHC or any other service.


Option 2: Pass Client Id in the response body with key xAdobeSignClientId

In the JSON response body with the key of xAdobeSignClientId and its value being the same client ID that was sent in the request header.

Replace the Index.js file with the following:

azure_case_2

module.exports = function (context, req) {

    var clientId = req.headers['x-adobesign-clientid'];

    // Validate that the incoming ClientID is genuine

    if (clientId === '123XXX456') {

        context.res = {

            // status: 200, /* Defaults to 200 */ // any 2XX response is acceptable

            body: {

                'xAdobeSignClientId' : clientId

            },

            headers : {

                'Content-Type' : 'application/json'

            }

        };

    }

    else {

        context.res = {

            status: 400,

            body: "Opps!! Illegitimate Call identified"

        };

    }

    context.done();

};

 

Test the behavior by mocking the request

1. Click on the Test button at extreme right corner

2. Mock the dummy request

azure_case_2_test

Also note the same behavior for clientID is expected when the Webhook URL receives POST notifications. 


Ready to Use

Once you have verified the behavior, the webhook URL is functional as per Adobe Sign standards. You can further update the custom logic as per your requirements.

 

Get the Function URL

  • Click on Get function URL
azure_get_url

 

Copy the URL and use it for creating webhooks in Adobe Sign

azure_get_functionurl


Configuration options

Configuring the Webhook requires five elements to be defined:

  • Name - An intuitive name that other admins can readily understand is suggested
  • Scope - How wide of a net is the webhook catching. Account and Group are available in the interface
    • The API supports Account, Group, User and Resource scopes
    • Only one Scope per webhook can be defined
  • URL - The target URL that Adobe Sign pushed the JSON payload to
  • Events - The trigger that causes Adobe Sign to build the JSON and push it to the URL
    • Each event builds a different payload relevant to the trigger event
    • Multiple Events can be included in one webhook
  • Notification Parameters - The Notification Parameters identify the sections of the Event JSON payload, allowing you to select only the sections of the Event that are important for this webhook (and thus reducing the unnecessary data in to your URL).

 

Once the webhook is fully defined, click Save, and the new webhook will start reacting to trigger events immediately. 

webhook_example


Scopes

  • Account: All the subscribed events occurring in the account trigger the push 
    • Account Admins have the authority to see all webhooks defined for the account/all groups
  • Group: All the subscribed events occurring in that group trigger the push. Group scoped webhooks exist in only one group
    • Group Admins will only see the webhooks that are dedicated to their group. They cannot see the Account level webhooks, or webhooks bound to other groups
  • User Account: All subscribed events for a user account trigger the push. User level webhooks can only be created via API
  • Resource level webhook: This will be created for a specific resource. Events specific to this resource will be pushed to the webhook URL. Resource-based webhooks can only be created via API


URL

A webhook URL is a server that listens for incoming HTTPS POST notification messages that are triggered when events occur.

You need this URL to subscribe your webhook to events.

  • The client must include an HTTPS URL that Adobe Sign can POST to. This URL must be available on the public internet.  
    • For example, 127.0.0.1 and localhost URIs will not work
  • Make sure the webhook supports POST requests for incoming event notifications and GET requests for the verification request
  • The URL should not be blocked by a firewall


Events

Below are the events that can trigger a push to the webhook URL, grouped by object.

Each event has a template of the JSON payload that can be delivered. (Click the name of the event to see the payload details):

  • Mega Sign - Mega Sign events pertain only to the creation of the Mega Sign parent object. The resultant child agreements are tracked as Agreement events.  
    • Mega Sign all events - All Mega Sign events are included. If additional events are defined in the future, they will be included automatically with this setting.  The JSON payload is based on the individual event that is triggered
    • Mega Sign created - When a Mega Sign is created
    • Mega Sign shared - When a Mega Sign is shared
    • Mega Sign recalled - When a Mega Sign is recalled
  • Widget - Widget events pertain only to the creation of the Widget template. The resultant child agreements are tracked as Agreement events.
    • Widget all events - All Widget events are included. If additional events are defined in the future, they will be included automatically with this setting.  The JSON payload is based on the individual event that is triggered
    • Widget created - When a widget is created
    • Widget enabled - When a widget is enabled
    • Widget disabled - When a widget is disabled
    • Widget modified - When a widget is modified
    • Widget shared - When a widget is shared
    • Widget creation failed - When a widget is auto-canceled due to a conversion problem


Notification Parameters

Notification Parameters allow you to customize the JSON payload to just specific elements of the event.

For example, in an Agreement participant replaced event, you may only want the Agreement Info and the Participant Info, leaving out the Document Info, and reducing the total volume into your webhook URL

 

  • Agreement
    • Agreement Info - Detailed agreement information based on the state of the agreement at the time of the triggering event
    • Agreement Document Info - Includes any document information generated as a result of the event
    • Agreement Participant Info - Includes any participant information as a result of the event
    • Agreement Signed Document - Provides the signed PDF. 
      • Applicable to the Agreement Workflow Completed and Agreement All events
  • Mega Sign
    • Mega Sign Info - Detailed information about the Mega Sign object that triggered the event
  • Widget
    • Widget Info - Detailed information about the Widget that triggered the event
    • Widget Document Info - The document information associated with the Widget template
    • Widget Participant Info - Information about the defined participants in the Widget template


Two-way SSL authentication

Two-way SSL, often called Client-Side SSL, is a mode of SSL wherein both the server and the client (web browser) present certificates to identify themselves.

Account admins can configure a client-side certificate on the Security Settings page.

Adobe Sign verifies the SSL certificates when delivering payloads to the webhook URL. Webhooks that fail the SSL certificate verification will not successfully deliver the JSON payload. 

Use Two-way SSL to authenticate the client (Adobe Sign) and listening service to ensure that only Adobe Sign can reach your webhook URL. 

ssl_cert


How to enable or disable

Access to the Webhooks feature is enabled by default for Enterprise accounts.

Group level admins can create/control the Webhooks that operate within their group only.

Access to the Webhooks page can be found in the left rail of the Admin menu: Account > Webhooks

navigate_to_webhooks


Activate a webhook

When a webhook is first created, it is created in an Active status.

On the Webhooks page in Adobe Sign, you will see the Active webhooks by default.

To activate an inactive webhook:

  • Click the Options icon (three horizontal lines) on the right of the webhooks header row and select Show All Webhooks
show_all_webhooks

 

  • Single click the inactive webhook to select it
    • This exposes the options for the webhook just under the header row
  • Click Activate

The active webhook will start sending data to the target URL as soon as the next event is triggered.

activate_webhook


Deactivate a webhook

Deactivating a webhook only requires that you

  • Navigate to the Webhooks page
  • Single click the webhook you want to deactivate
  • Select Deactivate from the menu items under the header row
    • Once deactivated, the webhook shows a status of Inactive
deactivate_a_webhook


View or Edit a webhook

Webhooks can be edited and saved at any time, and upon saving a new configuration, that change takes effect immediately.

Only the Events and Notification Parameters can be edited.

If the Name, Scope or URL needs to be changed, a new webhook will have to be created.

To edit the parameters of a webhook:

  • Navigate to the Webhooks page 
  • Single click the webhook you want to edit
  • Click the View/Edit option under the header row
edit_a_webhook

 

  • Apply any changes needed, and click Save
view_edit_panel


Delete a webhook

A webhook can be deleted at any time.

Deleting a webhook destroys it in the system, so there is no ability to recover a deleted webhook.

Webhooks do not need to be deactivated first.

To delete a webhook:

  • Navigate to Webhooks
  • Select the webhook you want to delete by single clicking it
  • Click the Delete option under the header row
  • A challenge is presented to ensure you want to delete the webhook. click OK
delete_a_webhook


Best Practices

  • Be duplicate resistant - If you have more than one app sharing the same webhook URL and the same user mapped to each app, the same event will be sent to your webhook multiple times (once per app). In some cases, your webhook may receive duplicate events. Your webhook application should be tolerant of this and dedupe by event ID.
  • Always respond to webhooks quickly - Your app only has ten seconds to respond to webhook requests. For the verification request, this is rarely an issue, since your app doesn't need to do any real work to respond. For notification requests, however, your app will usually do something that takes time in response to the request. 

For example, if you need to process and then store signed documents. To make sure you can always respond within ten seconds, you should always do your work on a separate thread or asynchronously using a queue.

  • Manage concurrency - When a user makes a number of changes in rapid succession, your app is likely to receive multiple notifications for the same user at roughly the same time. If you're not careful about how you manage concurrency, your app can end up processing the same changes for the same user more than once. 
  • In order to take advantage of Adobe Sign webhooks, a clear understanding of the use of the information needs to be understood. Be sure to ask questions such as: 

1. What data do you want to return in the payload? 

2. Who will be accessing this information? 

3. What decisions or reporting will be generated?

  • Recommendations for Receiving Signed Document - There are several factors to consider when determining how to receive a signed PDF from Adobe Sign in your document management system. 

While it is perfectly acceptable to just select the Agreement Signed Document option while creating webhook, you might consider using the Adobe Sign API to retrieve the documents when a triggering event (such as agreement status Complete) is received.


Things to keep in mind...

JSON size limitation

The JSON payload size is limited to 10 MB.

If an event generates a larger payload, a webhook will be triggered but the conditional parameter attributes, if there in the request, will be removed to reduce the size of the payload. 

"ConditionalParametersTrimmed " will be returned in the response when this happens to inform the client that the conditionalParameters info has been removed.

conditionalParametersTrimmed” is an array object containing the information about the keys that have been trimmed.

The truncation will be done in following order :

  • includeSignedDocuments
  • includeParticipantsInfo
  • includeDocumentsInfo
  • includeDetailedInfo

Signed Documents will be truncated first, followed by participant info, document info and finally detailed info.

This may happen, for example, on an agreement completion event if it includes signed document (base 64 encoded) as well or for an agreement with multiple form fields


Retry when the listening service is down

If the target URL for the webhook is down for any reason, Adobe Sign will queue the JSON and retry the push in a progressive cycle over 72 hours.

The undelivered events will be persisted in a retry queue and a best effort will be made over the next 72 hours to deliver the notifications in the order they occurred.

The strategy for retrying delivery of notifications is a doubling of time between attempts, starting with a 1-minute interval increasing to every 12 hours, resulting in 15 retries in the space of 72 hours.

If the webhook receiver fails to respond within 72 hours, the webhook will be disabled. No notifications will be sent to this URL until the webhook is activated again.

All notifications between the time the webhook is disabled and subsequently enabled again will be lost.

Dieses Werk unterliegt den Bedingungen der Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.  Twitter™- und Facebook-Beiträge fallen nicht unter die Bedingungen der Creative Commons-Lizenz.

Rechtliche Hinweise   |   Online-Datenschutzrichtlinie