Webhooks in Acrobat Sign

Last update: Jun 07, 2024.

data-slots=text
Announcement: All customers are migrating to webhooks 2.0 in 2023. For details, see http://www.adobe.com/go/acrobatsigndevrnotes.

Webhooks are developer-defined HTTPS requests that trigger when a subscribed event occurs. They allow for real-time notification of workflow events such as “signed” or “created” without having to poll Acrobat Sign for status; your app is automatically notified when an event occurs. The service simply makes an HTTPS POST request to the webhook’s HTTPS URL. In simple words, a webhook is a web service that accepts data or a stream of data from a source using a PUSH communication model. You can create webhooks can via the REST APIs as well as the Acrobat Sign web application.

While not explicitly stated, the webhook framework is the underlying mechanism used for multiple Acrobat Sign features; for example, any time a resource (agreement, webform, etc.)/user/group/account/application receives an event notification from Acrobat Sign, the “webhooks infrastructure” is in play.

Events are the reason for webhooks, and you control what events your Acrobat Sign integration listens for and how it responds. When a subscribed event occurs, Acrobat Sign constructs an HTTPS POST with a JSON body payload and delivers it to the specified URL. You can change the list of subscribed events through the API or UI anytime. Each event has a similar JSON schema based on the resource type, but the event type determines its unique payload object.

You can learn about and explore the JSON payloads by downloading the JSON files:

This guide provides details about each event, including:

Webhook changes

Webhooks regularly evolve with major releases. It’s a good idea to track updates by date from the Developer Release Notes

Best Practices

data-slots=text
See also “UI vs. API configuration” below.

UI vs. API configuration

You can customize the JSON payload via the web user interface or via the API. However, only a subset of the available parameters can be toggled on and off from the online UI. Moreover, the API provides for fine-tuning your JSON payloads. For this reason, we do not recommend that partners use this method for platform integrations.

The API “best practice”

As a best practice, set up webhooks via the API as a “resource” or per-agreement webhooks. There are a few reasons for this.

Polling as a “backup” update method

It is also recommended to set up some sort of “polling” mechanism and some way to re-create these “per-agreement” webhooks if the creation step has failed, and the agreements are still in some “non-terminal” state. It’s also recommended to configure some client-side monitoring that alerts you if the webhook creation process is failing. If you’re using the “per-agreement” process, your system will recognize that the issue has happened right away instead of needing to wait till customers complain about their agreement statuses not staying “current”. It’s also a good idea to automatically start the “polling” process for those agreements immediately on detecting webhook creation failure.

Update Agreement Status “manual” option

An additional “best practice” is to add an “update agreement status” button or trigger in your interface that “polls” Adobe Sign for a single agreement. If there is an issue, the user can manually update critical agreements and immediately get their status and/or a copy of the completed agreement. This is common for all of Acrobat Sign’s integrations.

Workflow example

Webhooks are a useful tool for apps that want to receive and process real-time data updates happening in Acrobat Sign; for example, after an agreement is signed, update the status of that agreement in an on-premises Content Management System like SharePoint.

Instead of requiring your application to make an API call every X number of minutes to check for a specific event in Sign (also known as polling), you can register webhooks and push HTTPS POST notifications to your webhook’s URL, thereby telling your application when an event occurs. This push-based model requires fewer API requests overall, provides you with real-time updates, and allows you to build more robust apps while updating your application instantly.

Acrobat Sign webhooks notifications are generated by changes to the agreement as it progresses from the creation to the sent, completed or aborted state. In the webhook notification, we provide updated information about the status of these agreements, optionally including detailed information about the agreement, the participants, and finally, the signed document.

A simple workflow for webhooks:

  1. A webhook client application (your app) calls POST /webhooks with a user token to register (“create”) a webhook for a resource.
  2. Acrobat Sign validates that the request and the webhook URL is valid. There is a defined mechanism for this validation where Acrobat Sign makes an HTTPS GET request (with the calling application’s client ID in a custom HTTPS request header) to the webhook URL and the webhook URL is expected to respond in a specific way; see Verification of intent.
  3. Acrobat Sign sends a success response (any HTTPS 2XX code) to your client app with the unique webhook identifier and location header which contains the URL of the webhook resource created in Acrobat Sign.
  4. Whenever an event happens in Acrobat Sign, a notification for that event is sent to the webhook URL.

Creating a webhook

Prerequisites

Before you can create webhooks in Acrobat Sign, do the following:

  1. Obtain a unique set of application credentials (an application ID and an application secret). Account administrators generate these credentials through the Acrobat Sign API page under “My Profile”.
  2. Webhook API calls require an OAuth access token. Each operation on a resource requires specific OAuth scope(s), and your application will need to request all of the needed scopes during the OAuth authorization process.
  3. Use the access token received from the OAuth authentication and authorization process in the following REST endpoints to perform operations on behalf of the user who authorized the API access.
  4. OAuth scopes for webhooks: Enable webhook scopes for your application before calling webhook APIs. The scopes webhook_read, webhook_write, and webhook_retention are needed to call GET, POST/PUT and DELETE APIs respectively.

Configure a webhook and subscribe to events

To create a webhook in Acrobat Sign, you must configure a webhook URL, register it as a webhook with Acrobat Sign, and subscribe to specific events. by calling the POST /webhooks API from the client application. The subscription specifies how a subscriber intends to consume events. At the most basic level, a subscription needs the following fields:

Verifying webhook URL intent

Before registering a webhook successfully, Acrobat Sign verifies that the webhook URL provided in the registration request really intends to receive notifications. For this purpose, receiving a new webhook registration request invokes 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 (Application ID) of the API application that is requesting to register the webhook. To register a webhook successfully, the webhook URL must respond to this verification request with an HTTPS 2XX response code, and it also MUST send back the same client ID value in one of the following two ways.

Method 1: Custom response header

You can respond to the verification request in a custom response header, X-ADOBESIGN-CLIENTID. This is the same header which was passed in the request, and can be echoed back in the response.

data-slots=heading, code

data-repeat=2

data-languages=JAVASCRIPT, JAVASCRIPT

Sample: JavaScript

// Fetch client id
var clientid = request.headers['X-ADOBESIGN-CLIENTID'];

//Validate it
if (clientid ==="BGBQIIE7H253K6") # gitleaks:allow //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

<?php
// Fetch client id
$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];
//Validate it
if($clientid == "BGBQIIE7H253K6") # gitleaks:allow //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
}
?>

Method 2: JSON response body

You can respond to the verification request in the JSON response body of the response with the key of xAdobeSignClientId and its value being the same client ID that was sent in the request.

data-slots=heading, code

data-repeat=3

data-languages=JAVASCRIPT, JAVASCRIPT, JSON

Sample: JavaScript

// Fetch client id
var clientid = request.headers['X-ADOBESIGN-CLIENTID'];
//Validate it
if (clientid ==="BGBQIIE7H253K6") # gitleaks:allow //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

<?php
// Fetch client id
$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];
//Validate it
if($clientid == "BGBQIIE7H253K6") # gitleaks:allow //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 response body

{
    "xAdobeSignClientId": "BGBQIIE7H253K6" /* gitleaks:allow */
}

The webhook is successfully registered only on a success response (2XX response code) and the validation of the client ID in either the header or response body. The purpose of this verification request is to demonstrate to Acrobat Sign that your webhook really does want to receive notifications at that URL. Had you accidentally entered the wrong URL, the webhook would fail to respond correctly to the verification-of-intent request, and Acrobat Sign would not send any notifications to that URL. Your app can also validate that it will receive notifications only through webhooks that 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 does not recognize that client ID, it MUST NOT respond with the success response code and Acrobat Sign will take care that the URL is not registered as a webhook.

The call to verify the webhook URL occurs in the following scenarios:

How to respond to a webhook notification

Acrobat Sign performs an implicit verification of intent in each webhook notification request that is sent to the webhook URL. Every webhook notification HTTPS request contains the customer HTTP header called X-ADOBESIGN-CLIENTID* The value of this header is the client ID (Application ID) of the application that created the webhook. We will consider the webhook notification successfully delivered, if and only if a success response (2XX response code) is returned and the client ID is sent in either the HTTP header (X-ADOBESIGN-CLIENTID) or in a JSON response body with key as xAdobeSignClientId and value as the same client ID; otherwise, Acrobat Sign will retry to deliver the notification to the webhook URL until the retries are exhausted.

Hosting your webhook in the cloud

Webhooks, as responsive functions, are ideally suited to hosting in the cloud. Several technology vendors have made available cloud-based, on-demand function execution platforms:

These platforms let you host webhook code in the cloud where it’s always ready to respond to Acrobat Sign. Using cloud-based functions offloads the most demanding functionality of your application to the cloud, and lets you build apps that can focus on functionality for the user without worrying about network loads and management.

Webhook properties

Webhook name

Use an intuitive name that other admins can readily understand.

Events

The list of your subscribed events.

Webhook URL

The webhook URL is The target URL where Acrobat Sign pushes the JSON payload. After you configure a webhook to listen on a given URL, register that URL with Acrobat Sign and use it to subscribe your webhook to the events.

Webhook status

Webhook scopes

Currently webhooks are supported at Account, Group, User Account, and Resource levels.

Webhook conditional parameters

Webhook payloads may include the minimum, default parameters, or additional and optional parameters.

When you register or update a webhook, you can specify whether you want to receive the minimum payload or detailed info such as participant info, document info, and more details using these parameters. By default, all the conditional parameters are set to false and Acrobat Sign sends the minimum payload (resourceId, status and name). Specify the following conditional parameters in the API request to receive the corresponding details in the payload:

Agreement

Library Document

Widget

MegaSign

Managing webhooks and subscriptions

Manage your webhooks via the webhook APIs. See the event guides for standard headers, error codes, and endpoint details:

Acrobat Sign: security and reliability

Webhook security

Acrobat Sign secures your webhooks in the following ways:

Reliable notifications: Retry policy

Acrobat Sign incorporates an advanced, reliable strategy for delivery of webhook notifications.

data-slots=text
You can check whether a webhook is enabled or disabled via the GET /webhooks/{webhook ID} API call. Note that the API does not tell you if the webhook is failing but has not yet been disabled.

© Copyright 2022, Adobe Inc.. Last update: Jun 07, 2024.