Acrobat.adobe.com Sent An Invalid Response

[Marilina Crawn]

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

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 is sent to your webhook multiple times (once per app). In some cases, your webhook may receive duplicate events. Your webhook application should process event IDs to avoid unnecessary handling of duplicate events.

Recommendations for signed documents: There are several factors to consider when determining how to receive a signed PDF from Acrobat Sign. 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 after receiving an Agreement Status Complete event.

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.

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.

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.

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.

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.

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.

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:

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.

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.

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.

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.

The client must include a public HTTPS URL to which Acrobat Sign can send a POST request. For example, 127.0.0.1 and localhost URIs will not work since the Acrobat Sign Service will not be able to contact your local computer.

Account level webhook: The webhook is created on an account for all the subscribed events happening in that account. To create an account-level webhook, specify the scope as ACCOUNT in the POST /webhooks API call. Account Admins have the authority to see all webhooks defined for the account and /all groups within that account.

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:

includeDetailedInfo: Determines whether agreement detailed info returns in the response payload. Based on the state of the agreement and the event being notified, the keys in the JSON payload will change.

includeSignedDocuments: Determines whether signed documents returns in the webhook response payload. If set to true, the signed document returns in base64-encoded format in JSON when signing is complete. This is sent only in the notification for the AGREEMENT_WORKFLOW_COMPLETED event.

includeDetailedInfo: Determines whether library document detailed info returns in the response payload. Based on the state of the library document and the event being notified, the keys in the JSON payload will change.

Validating webhooks subscription for authentication and authorization for webhooks created through the API: This is done using the existing API authentication and authorization validation in Sign. The first step for securing Acrobat Sign webhooks is to include the standard authentication mechanism (OAuth access token and authorization header). While setting up a webhook subscription, Sign validates that the token is valid and the API caller has permission to create a webhook on the resource. We will also validate that the API caller has appropriate authorization to create account-level webhooks.

Two-way SSL authentication: Acrobat Sign supports a two-way SSL handshake when making callbacks to customer servers. Two-way SSL, often called Client-Side SSL, is a mode of SSL wherein both the server and the client (web browser) present certificates to identify themselves. We allow the account admins, via their account Security Settings page, to upload an identifying certificate, which the Adobe Sign webhooks system uses to identify itself when making webhook calls to their servers. Acrobat Sign verifies SSL certificates when delivering payloads to HTTPS webhook addresses. Webhooks that fail the SSL certificate verification will not successfully deliver to their respective hosts. Please ensure your server is correctly configured to support HTTPS with a valid SSL certificate.

Sending and receiving the client ID in the webhook notification request: You can whitelist the client/application IDs through which you want to receive the payload. Notifications from the remaining apps can be ignored.

IP validation: To prevent setting an internal subnet (for example, a 10.x address), special IP address ranges such as the 169.254.169.254 range, and other invalid IP addresses as webhook URLs, Acrobat Sign validates the IP address at the time of webhook creation as well as while sending notifications. If the IP address is invalid, the webhook is not created. IP validation occurs as follows:

3a8082e126