Webhook APIs

Last update: Feb 06, 2024.

Webhook APIs are the means by which your integration communicates with the Acrobat Sign service about webhooks. Use the various API endpoints to create, delete, modify, and retrieve status information about your webhooks.

Acrobat Sign APIs include the endpoints described below.

POST /webhooks

POST Request object

{`{
    "name": "",
    "scope": "",
    "state": "",
    "webhookSubscriptionEvents": [
      ""
    ],
    "webhookUrlInfo": {
      "url": ""
    },
    "applicationDisplayName": "",
    "applicationName": "",
    "created": "",
    "id": "",
    "lastModified": "",
    "resourceId": "",
    "resourceType": "",
    "status": "",
    "webhookConditionalParams": {
      "webhookAgreementEvents": {
          "includeDetailedInfo": false,
          "includeDocumentsInfo": false,
          "includeParticipantsInfo": false,
          "includeSignedDocuments": false
      },
      "webhookMegaSignEvents": {
          "includeDetailedInfo": false
      },
      "webhookWidgetEvents": {
          "includeDetailedInfo": false,
          "includeDocumentsInfo": false,
          "includeParticipantsInfo": false
      }
    }
}`}

POST Response object

`WebhookCreationResponse  { "id" : "" }`

Error codes

Please note that new errors could be returned from APIs or existing error codes can be evolved. Clients are expected to be prepared to do default handling for error scenarios which they do not understand.

Error codes

This API will be used to create a webhook on a particular resource in Acrobat Sign.

• You need to register the webhook with your application and a user token using this API.
• Group level webhooks can only be created by a Group admin and Account level webhooks can only be created by an Account admin.
• The user can customize the events for which the webhook is triggered in this call.

The HTTP Location header field is returned in the response to provide information about the location of a newly created resource. Multiple webhooks can be created on a single resource. Also, multiple webhooks can share the same URL.

data-slots=text

webhookInfo {
...
  webhookEndpointInfo : {
    webhookEndpointId: "",
    domainPrefix: "",
    urlSuffix: ""
  }
}

webhookEndpointInfo Error codes

You should be prepared to handle new errors that may be returned from APIs or changes in existing error codes. It is important to note that error codes can evolve over time. You must be prepared to implement default error handling for unclear error events.

GET /webhooks

GET List Response object

WebhooksInfo
    
    {`{
    "userWebhookList": [
      {
          "applicationName": "Application for REST Swagger Documentation",
          "applicationId": "pUQL757H2R2",
          "id": "CBJCHBCAABAAtW5qb_gRDgssqn6tvLvCcav0VqYi0WTR",
          "name": "user level webhook",
          "lastModified": "2018-02-06T22:52:27-08:00",
          "scope": "USER",
          "webhookSubscriptionEvents": [
            "AGREEMENT_RECALLED"
          ],
          "webhookUrlInfo": {
            "url": "https://testUrl"
          },
          "status": "ACTIVE"
      },
      {
          "applicationName": "Application for REST Swagger Documentation",
          "applicationDisplayName ": "REST Swagger",
          "id": "CBJCHBCAABAAtW5qb_gRDgssqn6tvLvCcav0VqYi0WTR",
          "name": "webhook linked to a webhookEndpoint",
          "lastModified": "2018-02-06T22:52:27-08:00",
          "scope": "RESOURCE",
          "resourceType": "AGREEMENT",
          "resourceId": "3dffwifvgvfguierfreokfperfprfppr",
          "webhookSubscriptionEvents": [
            "AGREEMENT_RECALLED"
          ],
          "status": "ACTIVE",
          "webhookEndpointInfo": {
            "webhookEndpointId": "",
            "domainPrefix": "",
            "urlSuffix": ""
          }
      }
    ],
    "page": {
      "nextCursor": " "
    }
}`}

Error codes

Please note that new errors could be returned from APIs or existing error codes can be evolved. Clients are expected to be prepared to do default handling for error scenarios which they do not understand.

Error codes

GET /webhooks/{webhookId}

Get List by ID Response object

{`{
    "scope": "",
    "webhookSubscriptionEvents": [
        ""
    ],
    "webhookUrlInfo": {
        "url": ""
    },
    "name": "",
    "status": "",
    "applicationDisplayName ": "",
    "applicationName": "",
    "created": "date",
    "id": "",
    "lastModified": "date",
    "resourceId": "",
    "resourceType": "",
    "webhookConditionalParams": {
        "webhookAgreementEvents": {
            "includeDetailedInfo": false,
            "includeDocumentsInfo": false,
            "includeParticipantsInfo": false,
            "includeSignedDocuments": false
        },
        "webhookMegaSignEvents": {
            "includeDetailedInfo": false
        },
        "webhookWidgetEvents": {
            "includeDetailedInfo": false,
            "includeDocumentsInfo": false,
            "includeParticipantsInfo": false
        }
    }
  }`}

Error codes

Please note that new errors could be returned from APIs or existing error codes can be evolved. Clients are expected to be prepared to do default handling for error scenarios which they do not understand.

Error codes

data-slots=text

"userWebhookList": [
      {
          ...
          "webhookEndpointInfo": {
              "webhookEndpointId": "",
              "domainPrefix": "",
              "urlSuffix": ""
          }
      },

PUT /webhooks/{webhookId}

Put Request body

{`{
  "name": "",
  "scope": "",
  "state": "",
  "webhookSubscriptionEvents": [
    ""
  ],
  "webhookUrlInfo": {
    "url": ""
  },
  "applicationDisplayName": "",
  "applicationName": "",
  "created": "",
  "id": "",
  "lastModified": "",
  "resourceId": "",
  "resourceType": "",
  "status": "",
  "webhookConditionalParams": {
    "webhookAgreementEvents": {
        "includeDetailedInfo": false,
        "includeDocumentsInfo": false,
        "includeParticipantsInfo": false,
        "includeSignedDocuments": false
    },
    "webhookMegaSignEvents": {
        "includeDetailedInfo": false
    },
    "webhookWidgetEvents": {
        "includeDetailedInfo": false,
        "includeDocumentsInfo": false,
        "includeParticipantsInfo": false
    }
  }
}`}

Error codes

Please note that new errors could be returned from APIs or existing error codes can be evolved. Clients are expected to be prepared to do default handling for error scenarios which they do not understand.

Error codes

Only events and conditional parameters can be modified. The webhook URL can’t be modified once the webhook is created. The modification can also be done in the INACTIVE state.

data-slots=text

webhookInfo {
...
  webhookEndpointInfo : {
    webhookEndpointId: "",
    domainPrefix: "",
    urlSuffix: ""
  }
}

PUT /webhooks/{webhookId}/state

PUT State Request body

{ "state": ""}

Error codes

Please note that new errors could be returned from APIs or existing error codes can be evolved. Clients are expected to be prepared to do default handling for error scenarios which they do not understand.

Error codes

DELETE /webhooks/{webhookId}

Error codes

Please note that new errors could be returned from APIs or existing error codes can be evolved. Clients are expected to be prepared to do default handling for error scenarios which they do not understand.

Error codes

Standard API request error codes

Any API request may return any of these standard error codes:

Standard API request headers

Every API request will have the following standard headers. If Any API in the list above does not have one or more of the following headers, the API will explicitly document this fact.

Using AWS Lambda Functions

AWS Lambda Functions is a serverless computing service offered by Amazon Web Services. AWS Lambda Functions offer you a platform in which you can execute function code on demand over the internet without the need to manage your own web servers. This gives you a no-overhead solution for hosting functions in the cloud, such as webhooks for Acrobat Sign. AWS Lambda Functions support Node.js (JavaScript), Java, Python, C#, and Go.

Create an AWS Lambda function

To create an AWS Lambda function:

1. Login to your AWS Management Console and select the AWS Lambda service from the services list.

2. Choose to create a Lambda function, then select Author from Scratch.

3. In the Configure function page, enter the function name “lambdaWebhooks” and select Node.js 4.3 as the runtime.
4. For the role, choose an existing role or Create a new role from template(s).
5. If you have chosen Create new role from template(s), enter a role name (for instance, “role-lambda”) and select Simple Microservice permissions from the policy templates list.
6. Select Create function.
7. On the new AWS lambda function page, select Edit code inline as the code entry type; keep index.handler as the Handler.

Register your Acrobat Sign webhook

Before registering a webhook, Acrobat Sign verifies that the webhook URL that is provided in the registration request really intends to receive notifications; see verifyintent. For this purpose, when a new webhook registration request is received by Acrobat Sign, it first makes an HTTPS GET verification request 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 and register the webhook. The webhook URL must respond to this verification request with a 2XX response code, and it must send back the same client ID value in one of the following two ways: Also note the same behaviour for clientID is expected when the Webhook URL receives POST notifications.

Case 1: Pass the client ID as X-AdobeSign-ClientId in the response header

This is the same header which was passed in the request, and it must be echoed back in the response.

Replace the contents of the Index.js file with the following code snippet:

exports.handler = function index(event, context, callback) {
  // Fetch client id
  var clientid = event.headers['X-AdobeSign-ClientId'];

  //Validate it
  if (clientid =="BGB1234TESTKEY") //Replace 'BGB1234TESTKEY' with the client id of the application using which the webhook is created
  // gitleaks:allow
  {
    var response = {
        statusCode: 200,
        headers: {
            "X-AdobeSign-ClientId": clientid
        }
     };
   callback(null,response);
  }
  else {
   callback("Oops!! illegitimate call");
  }
}

Case 2: Pass the client ID in the response body with the key xAdobeSignClientId

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

Replace the contents of the Index.js file with the following code snippet:

exports.handler = function index(event, context, callback) {
 // Fetch client id
 var clientid = event.headers['X-AdobeSign-ClientId'];

 //Validate it
 if (clientid =="BGB1234TESTKEY") //Replace 'BGB1234TESTKEY' with the client id of the application using which the webhook is created 
 {
   var responseBody = {
        xAdobeSignClientId : clientid
   };

    var response = {
        statusCode: 200,
        body: JSON.stringify(responseBody)

    };
   callback(null,response);
 }
 else {
   callback("Opps!! illegitimate call");
  }
}

Save the function. The Lambda function is created, and you are almost ready to use it in a real-time webhook.

Configure the AWS API Gateway

To make this Lambda function publicly accessible through a HTTP method, you need to configure the AWS API Gateway using your function as the backend for the API.

1. In the AWS Management Console, select API Gateway from the AWS Services list.

Note: If this is your first time in the API Gateway console, you’ll see a Getting Started screen. Select Get Started to proceed. Clear the dialog for the example API. If you’ve used the API Gateway service before, simply select Create API to proceed.

2. In the Create new API page, select New API and enter webhooks as the API name.

3. Select Create API.
4. From the Actions drop-down list, select Create Resource.
5. Check the “Configure as proxy resource” option and enter validate as the Resource Name and {proxy+} in the Resource Path.
6. Leave the “Enable API Gateway CORS” option unchecked and select Create Resource.
7. Keep the Lambda Function Proxy selected as the Integration type and select the region where you have created your Lambda function in the Lambda region drop-down list (probably it’s the same region where you are creating the API Gateway).
8. Enter “validate” as the Lambda Function and select Save.
9. An Add Permission to Lambda Function pop-up window appears; select OK.

If all the above steps are executed successfully, you’ll see something like this:

Deploy the API

The next step is deploying this API so it becomes ready to use:

1. In the Actions drop-down, select Deploy API. The Deploy API dialog appears.
2. Select [New Stage] for the Deployment stage and enter “prod” (or anything you like to identify this stage) for the Stage name.
3. Select Deploy.

The new API is now ready to use. You can find the invoke URL in the blue box as shown below:

Take note of this URL as you’ll need to enter it as your real-time webhook URL.

Ready to Use

It’s done. Use the above URL with “{nodeJSfunctionName}” appended as the webhook URL in your POST /webhooks API request. Once you have verified the behavior, the webhook URL is functional as per Acrobat Sign standards. You can further update your new webhook and add custom logic as needed for your application.

Using Azure Functions

Azure Functions is Microsoft’s serverless computing cloud platform. Using Azure Functions, you can write functional code and host it in the Azure cloud, ready to execute on demand. This always-on functionality, combined with the ease of management offered by cloud-based serverless architecture, makes Azure Functions a viable alternative for hosting your Acrobat Sign webhooks.

Azure Functions executes individual serverless functions within a function app. Function apps can host many different functions, and you can have many function apps on Azure; so the infrastructure enables you to organize related functions into apps.

Prerequisites

To create and host a webhook in Azure Functions, you need:

1. A Microsoft account with license to create Azure Functions applications.

2. An Azure Functions app. If you don’t have an existing app, you can create it for the purpose: see Create your first function in the Azure portal in the Azure documentation.

3. For this example, basic knowledge of JavaScript. Azure Functions understands and executes functions written in several different languages; see Supported languages in Azure Functions in the Azure documentation.

Creating an Azure Functions Trigger-Webhook

Create a JS HttpTrigger function

1. Login with your Microsoft account at https://portal.azure.com/
2. Select Function Apps from your account dashboard menu. This will open your list of Azure Function apps.

3. Choose the app wherein you want to create this new function.
4. Select the + icon to create a new Azure function.

5. Select “Webhook + API” as the scenario and “JavaScript” as the language; then select “Create this function”.

This will create a new function that has the capability of handling incoming API requests.

Register the webhook

Register the webhook Before registering a webhook successfully, Acrobat Sign verifies that the webhook URL that is provided in the registration request really intends to receive notifications; see verifyintent. For this purpose, when a new webhook registration request is received by Acrobat Sign, it first makes an HTTPS GET verification request 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 and register the webhook. The webhook URL must respond to this verification request with a 2XX response code, and it must send back the same client ID value in one of the following two ways:

Case 1: Pass the client ID as ``X-AdobeSign-ClientId`` in the response header

This is the same header which was passed in the request, and it must be echoed back in the response.

1. Replace the contents of the index.js file with the following code snippet:

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();
};

2. Test the behavior by mocking the request:

• Select the Test button at the extreme right corner.
• Mock the dummy request:

Although the response headers are not shown above, you can observe them by mocking the request with developer tools such as Postman.

Case 2: Pass the client ID in the response body with the key ``xAdobeSignClientId``

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

1. Replace the index.js file with the following:

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();
};

2. Test the behavior by mocking the request:

• Select the Test button at the extreme right corner
• Mock the dummy request

Note: The same behavior for clientId is expected when the Webhook URL receives POST notifications.

Once you have verified the behavior, the webhook URL is functional as per Acrobat Sign standards. You can further update your new webhook and add custom logic as needed for your application.

Get the function’s URL

1. Select Get function URL:

2. Copy the URL and use it for creating webhooks in Acrobat Sign.

© Copyright 2022, Adobe Inc.. Last update: Feb 06, 2024.