Sample Javascript code to to fetch the client id, validate it, and then return it in the response header
What's New
Get Started
Administer
- Admin Console Overview
-
User Management
- Adding users
- Create function-focused users
- Check for users with provisioning errors
- Change Name/Email Address
- Edit a user's group membership
- Promote a user to an admin role
- User Identity Types and SSO
- Switch User Identity
- Authenticate Users with MS Azure
- Authenticate Users with Google Federation
- Product Profiles
- Login Experience
-
Account/Group Settings
- Settings Overview
-
Global Settings
- New Recipient Experience
- Self Signing Workflows
- Send in Bulk
- Web Forms
- Power Automate Workflows
- Library Documents
- Collect form data with agreements
- Limited Document Visibility
- Attach a PDF copy of the signed agreement
- Include a link in the email
- Include an image in the email
- Files attached to email will be named as
- Attach audit reports to documents
- Merge multiple documents into one
- Download individual documents
- Upload a signed document
- Set a default time zone
- Users in Multiple Groups (UMG)
- Group Administrator Permissions
- Replace recipient
- Audit Report
- Transaction Footer
- Healthcare customer
- Account Setup
-
Signature Preferences
- Well formatted signatures
- Custom Terms of Use and Consumer Disclosure
- Navigate recipients through form fields
- Restart agreement workflow
- Decline to sign
- Allow signers to print and place a written signature
- Require signers to use a mobile device to create their signature
- Request IP address from signers
- Digital Signatures
- Electronic Seals
- Digital Identity
-
Report Settings
- Security Settings
-
Send settings
- Require recipient name when sending
- Lock name values for known users
- Allowed recipient roles
- Allow e-Witnesses
- Recipient groups
- CCs
- Recipient Agreement Access
- Field flattening
- Modify Agreements
- Private messages
- Allowed signature types
- Reminders
- Send Agreement Notification through
- Signer identification options
- Content Protection
- Signing order
- Liquid mode
- Bio-Pharma Settings
- Notarization Settings
- Payments Integration
- SAML Settings
- Data Governance
- Time Stamp Settings
- External Archive
- Account Languages
- Email Settings
- Migrating from echosign.com to adobesign.com
- Configure Options for Recipients
-
Guidance for regulatory requirements
- Accessibility
- HIPAA
- GDPR
- 21 CFR part 11 and EudraLex Annex 11
- Healthcare customers
- IVES support
- "Vaulting" agreements
- EU/UK considerations
- Claim your domain
- Report Abuse links
Send, Sign, and Manage Agreements
-
Recipient Options
- Cancel an email reminder
-
Options on the e-signing page
- Overview of the e-sign page
- Open to read the agreement without fields
- Decline to sign an agreement
- Delegate signing authority
- Download a PDF of the agreement
- View the agreement history
- View the agreement messages
- Convert from an electronic to a written signature
- Convert from a written to an electronic signature
- Navigate the form fields
- Clear the data from the form fields
- E-sign page magnification and navigation
- Change the language used in the agreement tools and information
- Review the Legal Notices
- Adjust Acrobat Sign Cookie Preferences
- Send Agreements
-
Authoring fields into documents
- In-app authoring environment
- Create forms with text tags
- Create forms using Acrobat (AcroForms)
- Fields
- Authoring FAQ
- Sign Agreements
-
Manage Agreements
- Manage page overview
- Delegate agreements
- Replace Recipients
- Limit Document Visibility
- Cancel an Agreement
- Create new reminders
- Review reminders
- Cancel a reminder
- Access Power Automate flows
-
More Actions...
- How search works
- View an agreement
- Create a template from an agreement
- Hide/Unhide agreements from view
- Upload a signed agreement
- Modify a sent agreement's files and fields
- Edit a recipient's authentication method
- Add or modify an expiration date
- Add a Note to the agreement
- Share an individual agreement
- Unshare an agreement
- Download an individual agreement
- Download the individual files of an agreement
- Download the Audit Report of an agreement
- Download the field content of an agreement
- Audit Report
- Reporting and Data exports
Advanced Agreement Capabilities and Workflows
- Webforms
- Reusable Templates
- Transfer ownership of web forms and library templates
-
Power Automate Workflows
- Overview of the Power Automate integration and included entitlements
- Enable the Power Automate integration
- In-Context Actions on the Manage page
- Track Power Automate usage
- Create a new flow (Examples)
- Triggers used for flows
- Importing flows from outside Acrobat Sign
- Manage flows
- Edit flows
- Share flows
- Disable or Enable flows
- Delete flows
-
Useful Templates
- Administrator only
- Agreement archival
- Webform agreement archival
- Agreement data extraction
- Agreement notifications
- Agreement generation
- Custom Send workflows
- Share users and agreements
Integrate with other products
- Acrobat Sign for Salesforce
- Acrobat Sign for Microsoft
- Other Integrations
- Partner managed integrations
- How to obtain an integration key
Acrobat Sign Developer
- REST APIs
Support and Troubleshooting
Overview
A 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.
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.
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.
Concurrency-based rate limiting
Webhook (and callback) creation and notification events are limited in the number of concurrent notifications that are actively being delivered to the customer from the Acrobat Sign system. This limit applies to the account, to include all groups within the account.
This type of rate limiting prevents one poorly designed account from consuming a disproportionate amount of server resources, thereby negatively impacting all other customers in that server environment.
The number of concurrent events per account has been calculated to ensure that accounts with well-behaved webhooks will receive their notifications in the shortest amount of time and should rarely encounter a situation where notifications are delayed due to too many requests. The current thresholds are:
Action |
Maximum |
Description |
Webhook creation |
10 |
At most, 10 concurrent webhook creation requests are allowed per Account. |
Webhook/callback notification |
30 |
At most 30 concurrent webhook and callback notifications are allowed per Account. |
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
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.
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.