User Guide Cancel

Webhooks overview

 

Adobe Acrobat Sign Guide

What's New

  1. Pre-Release Notes
  2. Release Notes
  3. Important Notifications

Get Started

  1. Quick start guide for administrators
  2. Quick start guide for users
  3. For Developers
  4. Video tutorial library
  5. FAQ

Administer

  1. Admin Console Overview
  2. User Management
    1. Add a User
    2. Add Users in Bulk
    3. Add Users from your Directory
    4. Add Users from MS Azure Active Directory
    5. Create function-focused users
      1. Technical accounts - API driven
      2. Service accounts - Manually driven
    6. Check for users with provisioning errors
    7. Change Name/Email Address
    8. Edit a user's group membership
    9. Edit a user's group membership through the group interface
    10. Promote a user to an admin role
    11. User Identity Types and SSO
    12. Switch User Identity
    13. Authenticate Users with MS Azure
    14. Authenticate Users with Google Federation
    15. Product Profiles
    16. Login Experience 
  3. Account/Group Settings
    1. Settings Overview
    2. Global Settings
      1. Account tier and ID
      2. Self Signing Workflows
      3. Send in Bulk
      4. Web Forms
      5. Custom Send Workflows
      6. Power Automate Workflows
      7. Library Documents
      8. Collect form data with agreements
      9. Limited Document Visibility
      10. Attach a PDF copy of the signed agreement 
      11. Include a link in the email
      12. Include an image in the email
      13. Files attached to email will be named as
      14. Attach audit reports to documents
      15. Merge multiple documents into one
      16. Upload a signed document
      17. Delegation for users in my account
      18. Allow external recipients to delegate
      19. Authority to sign
      20. Authority to send
      21. Power to add Electronic Seals
      22. Set a default time zone
      23. Set a default date format
      24. Users in Multiple Groups (UMG)
        1. Upgrade to use UMG
      25. Group Administrator Permissions
      26. Replace recipient
      27. Audit Report
        1. Overview
        2. Allow unauthenticated access on the transaction verification page
        3. Include reminders
        4. Include view events
        5. Include agreement page/attachment count
      28. In Product Messaging and Guidance
      29. Accessible PDFs
      30. New authoring experience
      31. Healthcare customer
    3. Account Setup
      1. Add logo
      2. Customize company Hostname/URL    
      3. Add company name
    4. Signature Preferences
      1. Well formatted signatures
      2. Allow recipients to sign by
      3. Signers can change their name
      4. Allow recipients to use their saved signature
      5. Custom Terms of Use and Consumer Disclosure
      6. Navigate recipients through form fields
      7. Decline to sign
      8. Allow Stamps workflows
      9. Require signers to provide their Title or Company
      10. Allow signers to print and place a written signature
      11. Show messages when e-signing
      12. Require signers to use a mobile device to create their signature
      13. Request IP address from signers
      14. Exclude company name and title from participation stamps
    5. Digital Signatures
      1. Overview
      2. Download and sign with Acrobat
      3. Sign with Cloud Signatures
      4. Include metadata for Identity Providers
      5. Restricted Cloud Signatures Providers
    6. Electronic Seals
    7. Digital Identity
      1. Digital Identity Gateway
      2. Identity Check policy
    8. Report Settings
      1. New report experience
      2. Classic report settings
    9. Security Settings
      1. Single Sign-on settings
      2. Remember-me settings
      3. Login password policy
      4. Login password strength
      5. Web session duration
      6. PDF encryption type
      7. API
      8. User and group info access
      9. Allowed IP Ranges
      10. Account Sharing
      11. Account sharing permissions
      12. Agreement sharing controls
      13. Signer identity verification
      14. Agreement signing password
      15. Document password strength
      16. Block signers by Geolocation
      17. Phone Authentication
      18. Knowledge-Based Authentication (KBA)
      19. Allow page extraction
      20. Document link expiration
      21. Upload a client certificate for webhooks/callbacks
      22. Timestamp
    10. Send settings
      1. Show Send page after login
      2. Require recipient name when sending
      3. Lock name values for known users
      4. Allowed recipient roles
      5. Recipient groups
      6. Required fields
      7. Attaching documents
      8. Field flattening
      9. Modify Agreements
      10. Agreement name
      11. Languages
      12. Private messages
      13. Allowed signature types
      14. Reminders
      15. Signed document password protection
      16. Signer identification options
        1. Overview
        2. Signing password
        3. One-Time Password via Email
        4. Acrobat Sign authentication
        5. Phone authentication
        6. Cloud-based digital signature
        7. Knowledge-based authentication
        8. Government ID
        9. Signer Identity reports
      17. Content Protection
      18. Enable Notarize transactions
      19. Document Expiration
      20. Preview, position signatures, and add fields
      21. Signing order
      22. Liquid mode
      23. Custom workflow controls
      24. Upload options for the e-sign page
      25. Post-sign confirmation URL redirect
    11. Message Templates
    12. Bio-Pharma Settings
      1. Overview
      2. Enforce identity authentication
      3. Signing reasons
    13. Workflow Integration
    14. Notarization Settings
    15. Payments Integration
    16. Signer Messaging
    17. SAML Settings
      1. SAML Configuration
      2. Install Microsoft Active Directory Federation Service
      3. Install Okta
      4. Install OneLogin
      5. Install Oracle Identity Federation
    18. Data Governance
    19. Time Stamp Settings
    20. External Archive
    21. Account Languages
    22. Email Settings
      1. Email header/footer images
      2. Permit individual user email footers
      3. Customize the Signature Requested email
      4. Customize the To and CC fields
      5. Custom email templates
      6. Enable Linkless Notifications
    23. Migrating from echosign.com to adobesign.com
    24. Configure Options for Recipients
  4. Guidance for regulatory requirements
    1. Accessibility
      1. Accessibility Compliance
      2. Create accessible forms with Acrobat desktop
      3. Create accessible AcroForms
    2. HIPAA
    3. GDPR
      1. GDPR Overview
      2. Redact a user
      3. Redact a user's agreements    
    4. 21 CFR part 11 and EudraLex Annex 11
      1. 21 CRF part 11 validation pack
      2. 21 CFR and EudraLex Annex 11 handbook
      3. Analysis of shared responsibilities
    5. Healthcare customers
    6. IVES support
    7. eOriginal vaulting for chattel paper
    8. EU/UK considerations
      1. EU/UK Cross-border transactions and eIDAS
      2. HMLR requirements for deeds signed electronically
      3. The impact of Brexit on e-signature laws in the UK
  5. Download Agreements in Bulk
  6. Claim your domain 

Send, Sign, and Manage Agreements

  1. Recipient Options
    1. Cancel an email reminder
    2. Options on the e-signing page
      1. Overview of the e-sign page
      2. Open to read the agreement without fields
      3. Decline to sign an agreement
      4. Delegate signing authority
      5. Restart the agreement
      6. Download a PDF of the agreement
      7. View the agreement history
      8. View the agreement messages
      9. Convert from an electronic to a written signature
      10. Convert from a written to an electronic signature 
      11. Navigate the form fields
      12. Clear the data from the form fields
      13. E-sign page magnification and navigation
      14. Change the language used in the agreement tools and information
      15. Review the Legal Notices
      16. Adjust Acrobat Sign Cookie Preferences
  2. Send Agreements  
    1. Send page overview
    2. Send an agreement only to yourself
    3. Send an agreement to others
    4. Written Signatures
    5. Recipient signing order
    6. Send in Bulk
      1. Overview of the Send in Bulk feature
      2. Send in Bulk - manual recipients
      3. Send in Bulk - CSV upload
      4. Cancel a Send in Bulk transaction
      5. Add reminders to Send in Bulk
      6. Reporting for Send in Bulk
  3. Authoring fields into documents
    1. In-app authoring environment
      1. Automatic field detection
      2. Drag and drop fields using the authoring environment
      3. Assign form fields to recipients
      4. The Prefill role
      5. Apply fields with a reusable field template
      6. Transfer fields to a new library template
      7. Updated authoring environment when sending agreements
    2. Create forms with text tags
    3. Create forms using Acrobat (AcroForms)
      1. AcroForm creation
      2. Creating accessible PDFs
    4. Fields
      1. Field types
        1. Common field types
        2. In-line Images
        3. Stamp Images
      2. Field content appearance
      3. Field validations
      4. Masked fields values
      5. Setting show/hide conditions
      6. Calculated fields 
    5. Authoring FAQ
  4. Sign Agreements
    1. Sign agreements sent to you
    2. Fill & Sign
    3. Self-signing
  5. Manage Agreements
    1. Manage page overview
    2. Delegate agreements
    3. Replace Recipients
    4. Limit Document Visibility 
    5. Cancel an Agreement 
    6. Create new reminders
    7. Review reminders
    8. Cancel a reminder
    9. More Actions...
      1. How search works
      2. View an agreement
      3. Create a template from an agreement
      4. Hide/Unhide agreements from view
      5. Upload a signed agreement
      6. Modify a sent agreement's files and fields
      7. Edit a recipient's authentication method
      8. Add or modify an expiration date
      9. Add a Note to the agreement
      10. Share an individual agreement
      11. Unshare an agreement
      12. Download an individual agreement
      13. Download the individual files of an agreement
      14. Download the Audit Report of an agreement
      15. Download the field content of an agreement
  6. Audit Report
  7. Reporting and Data exports
    1. Overview
    2. Grant users access to reporting
    3. Report charts
      1. Create a new report
      2. Agreement Reports
      3. Transaction Reports
      4. Settings Activity Report
      5. Edit a report
    4. Data Exports 
      1. Create a new data export
      2. Edit a data export
      3. Refresh the data export content
      4. Download the data export
    5. Rename a report/export
    6. Duplicate a report/export
    7. Schedule a report/export
    8. Delete a report/export
    9. Check Transaction Usage

Advanced Agreement Capabilities and Workflows

  1. Webforms 
    1. Create a web form
    2. Edit a web form
    3. Disable/Enable a web form
    4. Hide/Unhide a web form
    5. Find the URL or script code 
    6. Prefill web form fields with URL parameters
    7. Save a web form to complete later
    8. Resize a web form
  2. Reusable Templates (Library templates) 
    1. US Government forms in the Acrobat Sign library
    2. Create a library template
    3. Change a library template's name
    4. Change a library template's type
    5. Change a library template's permission level
    6. Copy, edit, and save a shared template
    7. Download the aggregate field data for a library template
  3. Transfer ownership of web forms and library templates
  4. Power Automate Workflows 
    1. Overview of the Power Automate integration and included entitlements
    2. Enable the Power Automate integration
    3. Track Power Automate usage
    4. Create a new flow (Examples)
    5. Triggers used for flows
    6. Importing flows from outside Acrobat Sign
    7. Manage flows
    8. Edit flows
    9. Share flows
    10. Disable or Enable flows
    11. Delete flows
    12. Useful Templates
      1. Administrator only
        1. Save all completed documents to SharePoint
        2. Save all completed documents to OneDrive for Business
        3. Save all completed documents to Google Drive
        4. Save all completed documents to DropBox
        5. Save all completed documents to Box
      2. Agreement archival
        1. Save your completed documents to SharePoint
        2. Save your completed documents to One Drive for Business
        3. Save your completed documents to Google Drive
        4. Save your completed documents to DropBox
        5. Save your completed documents to Box
      3. Webform agreement archival
        1. Save completed web form documents to SharePoint Library
        2. Save completed web form documents to OneDrive for Business
        3. Save completed   documents to Google Drive
        4. Save completed web form documents to Box
      4. Agreement data extraction
        1. Extract form field data from your signed document and update Excel sheet
      5. Agreement notifications
        1. Send custom email notifications with your agreement contents and signed agreement
        2. Get your Adobe Acrobat Sign notifications in a Teams Channel
        3. Get your Adobe Acrobat Sign notifications in Slack
        4. Get your Adobe Acrobat Sign notifications in Webex
      6. Agreement generation
        1. Generate document from Power App form and Word template, send for signature
        2. Generate agreement from Word template in OneDrive, and get signature
        3. Generate agreement for selected Excel row, send for review and signature
  5. Custom Send workflows
    1. Custom Send Workflow Overview
    2. Creating a new Send Workflow
    3. Edit a Send Workflow
    4. Activate or Deactivate a Send Workflow
    5. Send an agreement with a Send Workflow
  6. Share users and agreements
    1. Share a user
    2. Share agreements

Integrate with other products

  1.  Acrobat Sign integrations overview 
  2. Acrobat Sign for Salesforce
  3. Acrobat Sign for Microsoft
    1. Acrobat Sign for Microsoft 365
    2. Acrobat Sign for Outlook
    3. Acrobat Sign for Word/PowerPoint
    4. Acrobat Sign for Teams
    5. Acrobat Sign for Microsoft PowerApps and Power Automate
    6. Acrobat Sign Connector for Microsoft Search
    7. Acrobat Sign for Microsoft Dynamics 
    8. Acrobat Sign for Microsoft SharePoint 
  4. Other Integrations
    1. Acrobat Sign for ServiceNow
    2. Acrobat Sign for HR ServiceNow
    3. Acrobat Sign for SAP SuccessFactors
    4. Acrobat Sign for Workday
    5. Acrobat Sign for NetSuite
    6. Acrobat Sign for VeevaVault
    7. Acrobat Sign for Coupa BSM Suite
  5. Partner managed integrations
  6. How to obtain an integration key

Acrobat Sign Developer

  1. REST APIs 
    1. Methods documentation
    2. SDK/Developer Guide
    3. API FAQ    
  2. Webhooks 
    1. Webhook overview
    2. Configure a new webhook
    3. View or edit a webhook
    4. Deactivate or reactivate a webhook
    5. Delete a webhook
    6. Two-way SSL certificates
    7. Webhooks in the API

Support and Troubleshooting

  1. Customer Support Resources 
  2. Enterprise Customer Success Resources 

Overview

webhook is a user-defined HTTPS request triggered when a subscribed event occurs at the source site (Adobe Acrobat Sign, in this case).

Effectively, a webhook is nothing but a REST service that accepts data or a stream of data.

Webhooks are meant for service-to-service communication in a PUSH model.

When a subscribed event is triggered, Acrobat Sign constructs an HTTPS POST with a JSON body and delivers that to the URL specified.

Before configuring webhooks, make sure that your network will accept the IP ranges needed for functionality.

 

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

  • Admins can enable their webhooks without having to involve Acrobat Sign support to list the callback URL
  • Webhooks are better in terms of data "freshness," the 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 a more straightforward configuration of modern applications
  • Multiple webhooks can be configured per scope (Account/Group/User/Resource), where Callbacks were required to be unique
  • Webhooks allow for the 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.
Note:

This document is primarily focused on the Webhooks UI in the Acrobat Sign web application (Previously Adobe Sign).

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

Prerequisites

You must allow the IP ranges for webhooks through your network security for the service to work. 

The legacy callback URL service in REST v5 uses the same IP ranges as the webhook service.

Administrators can log in to the Adobe Admin Console to add users. Once logged in, navigate to the administrator's menu and scroll down to Webhooks.

How it's used

Admins will first need to have a webhook service, ready to accept the inbound push from Acrobat 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 Acrobat Sign admin can create a new webhook from the Webhook interface in the Account menu of the Acrobat  Sign site.

Admins can configure the webhook to trigger for Agreement, Web form (Widget), or Send in Bulk (MegaSign) events. Library Template (Library Document) resource can also be configured through the API.

The scope of the webhook can include the whole account or individual groups through the admin interface. The API allows for more granularity through the selection of USER or RESOURCE scopes.

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

Once the webhook is configured and saved, Acrobat Sign will push a new JSON object to the defined URL every time the subscribed event is triggered. 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, Acrobat Sign verifies whether the webhook URL that is provided in the registration request intends to receive notifications or not. For this purpose, when Acrobat Sign receives a new webhook registration request, it first makes a verification request to the webhook URL. This verification request is an HTTPS GET request sent to the webhook URL. This request has a custom HTTP header X-AdobeSign-ClientId. The value in this header is set to the client ID (Application ID) of the API application 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 passed in the request and echoed back in the response.
  • Or in the JSON response body with the key of xAdobeSignClientId and its value being the same client ID 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 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 Acrobat 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 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 Acrobat Sign will take care that the URL is not registered as a webhook.

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

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

How to respond to a webhook notification

Acrobat Sign performs an implicit verification of intent in each webhook notification request sent to the webhook URL. Thus, every webhook notification HTTPS request also contains the custom 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 via 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.

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"

}

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 Acrobat 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.

Navigate to Function Apps in Azure

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

Create an Azure function

 

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 Acrobat Sign 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 or not. For this purpose, when a new webhook registration request is received by Acrobat 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:

Replace the index.js file

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

Test the function

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:

Update the index.js file content

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

Test the function

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 Acrobat Sign standards. You can further update the custom logic as per your requirements.

 

Get the Function URL

  • Click on Get function URL
GEt the function URL

 

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

Copy the function URL

Creating the AWS Lambda function

To create an AWS Lambda function, login to your AWS Management Console and select the AWS Lambda service from the services list.

  • Click Create a Lambda function using "Author From Scratch" option
  • In the Configure function page enter the function name "lambdaWebhooks" and select Node.js 4.3 as the Runtime
  • For the Role choose an existing role or create a new role from template(s)
    • If you have chosen  Create new role from template(s) enter a role name (e.g. role-lamda) and select Simple Microservices permissions from the Policy templates list
  • Click the Create function button
Create a function on AWS

  • On the new AWS lamda function page, select "Edit code inline" as "Code entry type", keep the index.handler as Handler.
  • Add logic to register the Acrobat  Sign 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 or not. For this purpose, when a new webhook registration request is received by Acrobat 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. Also note the same behavior for clientID is expected when the Webhook URL receives POST notifications. 

    Follow either of the two cases:

    Case 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.

      Code Snippet
      In index.js file, replace the automatically generated code snippet with the following code:

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

exports.handler = function index(event, context, callback) {

  // Fetch client id

  var clientid = event.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 response = {

        statusCode: 200,

        headers: {

            "X-AdobeSign-ClientId": clientid

        }

     };

   callback(null,response);

  }

  else {

   callback("Oops!! illegitimate call");

  }

}

 

Case 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.

 

Code Snippet

Replace the Index.js file with the following :

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

exports.handler = function index(event, context, callback) {

 // Fetch client id

 var clientid = event.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

   };

     

    var response = {

        statusCode: 200,

        body: JSON.stringify(responseBody)

    };

 

   callback(null,response);

 }

 else {

   callback("Opps!! illegitimate call");

  }

}

Update the index.js file content

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

 

Configuring the AWS API Gateway

To make this Lambda publicly accessible through an HTTP method, we need to configure the AWS API Gateway using our function(created above) as the backend for the API.

In AWS Management Console select the API Gateway from the AWS services and click Create API button

Configure the API gateway

  • In the Create new API page select New API and enter webhooks as the API name.
  • Click the Create API button
  • Select the Actions drop-down list and select the Create Resource option
  • Check the Configure as proxy resource option and enter validate as the Resource Name and {proxy+} in the Resource Path
  • Leave the Enable API Gateway CORS option unchecked and click the Create Resource button
  • Keep the Lambda Function Proxy selected as 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).
  • Enter validate as the Lambda Function and click the Save button
  • In the Add Permission to Lambda Function pop-up window select OK

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

Configured method

Deploying API

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

  • In the Actions drop-down select Deploy API
  • Select [New Stage] in the Deployment stage and enter prod (or anything you like to identify this stage) in the Stage name
  • Click the Deploy button

API is now ready to use and you can find the invoke URL in the blue box as shown below:

Deploy the API

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 this above url with "/{nodeJSfunctionName}" appended as webhook url in POST /webhooks API request.  Once you have verified the behavior, the Webhook URL is functional as per
Acrobat Sign standards. You can further update/add the custom logic as per your requirement.

How to enable or disable

Access to the Webhooks feature is enabled by default for enterprise tier 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.

Navigate to the webhooks tab

Best Practices

  • Subscribe to specific, needed events to limit the number of HTTPS requests to the server - The more specific you can make your webhooks, the less volume you'll need to sift through.
  • 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 five 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. It is recommended to work on a separate thread or asynchronously using a queue to ensure you can respond within five seconds
  • 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 Acrobat Sign webhooks, a clear understanding of the use of the information needs to be understood. Be sure to ask questions such as: 
    • What data do you want to return in the payload? 
    • Who will be accessing this information? 
    • What decisions or reporting will be generated?
  • Recommendations for receiving a signed document - There are several factors to consider when determining how to receive a signed PDF from Acrobat Sign in your document management system. 

While it is perfectly acceptable to just select the Agreement Signed Document option while creating a webhook, you might consider using the Acrobat 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

Webhook notifications

Acrobat Sign webhooks deliver notifications to the sender of the agreement, and any webhook configured within the group from which the agreement was sent. Account scoped webhooks receive all events.

Sender: User A | Signer: User B | Sharee: User C

User A and User B are in different accounts

User A and User C are in different accounts

Use-case

Notification?

Comments/Notes

User A's account has ACCOUNT level webhook (created by User A or Account Admin).

Yes

An ACCOUNT level webhook gets notified of all events triggered in that account.

User A's account has GROUP level webhook (created by User A or Account/Group Admin).

Assumption: User A & Group Admin are in the same group.

Yes

A GROUP level webhook gets notified of all events triggered in that group.

User A has USER level webhook.

Yes

As the Sender, User A's USER level webhook is triggered

User A has RESOURCE level webhook (for above-sent agreement).

Yes

 
     

User B's account has ACCOUNT level webhook (created by User B or Account Admin).

No

User B's ACCOUNT level webhook is considered a Signer webhook.

User B's account has GROUP level webhook (created by User B or Account/Group Admin).

Assumption: User B & Group Admin are in the same group.

No

User B's GROUP level webhook is considered a Signer webhook.

User B has USER level webhook.

No

User B's USER level webhook is considered a Signer webhook.

     

User C's account has ACCOUNT level webhook (created by User C or Account Admin).

No

User C's ACCOUNT level webhook is considered a non-originator webhook.

User C's account has GROUP level webhook (created by User C or Account/Group Admin).

Assumption: User C & Group Admin are in the same group.

No

User C's GROUP level webhook is considered a non-originator webhook.

User C has USER level webhook.

No

User C's USER level webhook is considered a non-originator webhook.

Sender: User A | Signer: User B | Sharee: User C

User A,  User B, and User C are in the same account

Use-case

Notification?

Notes

User A's account has ACCOUNT level webhook (created by User A or Account Admin).

Yes

ACCOUNT level webhooks notify for events triggerd by the account.

User A's account has GROUP level webhook (created by User A or Account/Group Admin).

Assumption: User A & Group Admin are in same group.

Yes

GROUP level webhooks notify for events triggerd by the users in their group.

User A has USER level webhook.

Yes

As the Sender, User A's User level webhook is triggered

User A has RESOURCE level webhook (for the above sent agreement).

Yes

 
     

User B's account has ACCOUNT level webhook (created by User B or Account Admin).

Yes

Since User A and User B are in the same account, an ACCOUNT level webhook gets notified of all events triggered in that account.

User B's account has GROUP level webhook (created by User B or Account/Group Admin).

Assumption: User A, User B & Group Admin are in same group.

Yes

Since User A & User B are in the same group, a GROUP level webhook gets notified of all events triggered in that group.

User B's account has GROUP level webhook (created by User B or Account/Group Admin).

Assumption: User A & User B are in different groups.

No

User B's GROUP level webhook is considered a Signer webhook.

User A's webhook (RESOURCE/USER/GROUP/ACCOUNT) will be triggered.

User B has USER level webhook.

No

As a recipient, User B's USER level webhook is not triggered.

     

User C's account has ACCOUNT level webhook (created by User C or Account Admin).

Yes

Since User A and User C are in the same account, an ACCOUNT level webhook gets notified of all events triggered in that account.

User C's account has GROUP level webhook (created by User C or Account/Group Admin).

Assumption: User A, User C & Group Admin are in same group.

Yes

Since User A and User C are in the same group, a GROUP level webhook gets notified of all events triggered in that group.

User C's account has GROUP level webhook (created by User C or Account/Group Admin).

Assumption: User A & User C are in different groups.

No

User C's GROUP level webhook is considered a non-originator webhook.

User A's webhook (RESOURCE/USER/GROUP/ACCOUNT) will be triggered.

User C has USER level webhook.

No

User C's USER level webhook is considered a non-originator webhook.

Retry when the listening service is down

If the target URL for the webhook is down for any reason, Acrobat 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, and there have been no successful notification deliveries in the last seven days, 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.

 Adobe

Get help faster and easier

New user?