Webhooks OAuth 2.0 User Guide¶

Prerequisites¶

To use Webhook OAuth 2.0, the account level setting, WEBHOOK_OAUTH20_ROLLOUT needs to be set. You must reach out to Adobe customer support to get this enabled.

Using Webhooks OAuth 2.0¶

Create a customer application.

Enable the following scopes for the application:
- webhook_read
- webhook_write
- webhook_retention

Follow these steps to generate access_token to authorize requests for a Acrobat Sign API endpoint.
To create a WebhookEndpoint, send a POST request to the /api/rest/v6/accounts/{accountId}/webhookEndpoints with the following JSON body:

webhookEndpoints_POST_curl

curl --location 'https://api.na1.adobesignpreview.com/api/rest/v6/accounts/CBJCHBCAABAAHVF2SeYL6q68j8ttKbJ7stmVG59DtWJT/webhookEndpoints' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 3AAABLKmtbUBUicE9oSp05' \
--data '{
    "name" : "preview_na1_12_19_2023_1",
    "description": "preview_na_12_19_2023_1_description",
    "webhookEndpointUrl": "https://*.domain.subdomain.com/somePath?someQueryParam=*",
    "applicationIds": ["CBJCHBCAABAAhdTfTbSnTtEqZf_cLHgqnXwNqqucWvWa"],
    "oAuth20": {
      "authorizationServerUrl": "https://your.authorization-server.url",
      "clientId": "auth-server-client-id",
      "clientSecret": "auth-server-client-secret",
      "scope": "optional-scope-for-auth-server",
      "customHeaders": [
        {
          "header": "optional-header",
          "value": "optional-header-value"
        }
      ]
    }
}'

Note

Adobe Acrobat Sign uses the credentials provided in the OAuth2.0 to call the authorization server URL to get the access_token before a webhook notification. A standard response from the authorization server contains the following fields:

access_token: It is the only mandatory field.
refresh_token: It is an optional field.
token_type: Bearer token type is supported.
expires_in: It is measured in seconds.

{
  "access_token":"HereIsYourSuperSecretAccessToken",
  "refresh_token":"HereIsYourSuperSecretRefreshToken",
  "token_type":"Bearer",
  "expires_in":3600
}

webhookEndpoints_POST

POST /api/rest/v6/accounts/{accountId}/webhookEndpoints HTTP/1.1
Host: api.na1.echosign.com
Authorization: Bearer 3AAABLKmtbUBUicE9oSp05
Content-Type: application/json

{
    "name" : "preview_na1_12_19_2023_1",
    "description": "preview_na_12_19_2023_1_description",
    "webhookEndpointUrl": "https://*.domain.subdomain.com/somePath?someQueryParam=*",
    "applicationIds": ["CBJCHBCAABAAhdTfTbSnTtEqZf_cLHgqnXwNqqucWvWa"],
    "oAuth20": {
      "authorizationServerUrl": "https://your.authorization-server.url",
      "clientId": "auth-server-client-id",
      "clientSecret": "auth-server-client-secret",
      "scope": "optional-scope-for-auth-server",
      "customHeaders": [
        {
          "header": "optional-header",
          "value": "optional-header-value"
        }
      ]
    }
}

Replace the value for the following attributes with the correct values:

Attributes¶
Attribute	Description
name	Name of the webhookEndpoint resource that you want to create. It’s length cannot be more than 255 characters.
description	Optionally, add a description for the webhookEndpoint.
webhookEndpointUrl	This is a webhookEndpoint URL pattern that you would like to be mapped to one or more webhook(s) that belong to the same account. See webhookEndpointUrl details.
applicationIds	One or more Application IDs (for example Step.1) that needs to be associated. This would be alphanumeric.
authorizationServerUrl	URL of the authorization server for getting the access token.
clientId	clientId for the authorization server.
clientSecret	client secret for the authorization server.
scope	scope, if any, needed for the authorization server.
customHeaders	A map of key-value pairs that you want in webhook notification request for increased personalization.

webhookEndpointUrl details¶

For webhookEndpointUrl, you can provide a leading and a trailing wildcard that would be replaced with respective values (domainPrefix and urlSuffix) when the webhook(s) are created by providing the webhookEndpointId, in addition to that.

Example webhookEndpointUrl: https: //yourDomain.com/webhook?agreementID=

You can link this webhookEndpointUrl to any new webhooks you create by using the id from the response in webhookEndpointInfo. Include domainPrefix and urlSuffix if you’re using wildcards. After associating the webhookEndpoint resource using the webhookEndpointId, with domainPrefix as “dev-01” and urlSuffix as “agreement123,” the resulting webhookUrl for /api/rest/v6/webhooks will be as follows: https: //dev-01.yourDomain.com/webhook?agreementId=agreement123

You will get the following response containing the id:

{
    "id": "e6a238bc-1c67-463c-992c-9edc9ba637a7"
}

The returned id is used to uniquely identify the webhookEndpoint.

To associate the above webhookEndpoint for a new webhook, send a POST request to /api/rest/v6/webhooks with the following JSON body:

Note

The webhookUrlInfo is not required when creating a webhook linked to a webhookEndpoint.

POST /api/rest/v6/webhooks HTTP/1.1
Host: api.na1.echosign.com
Authorization: 3AAABLKmtbUBUicE9oSp05
Content-Type: application/json

{
    "name": "preview_na1_webhook_12_19_2023_1",
    "scope": "USER",
    "state": "ACTIVE",
    "webhookSubscriptionEvents": [
        "AGREEMENT_ACTION_COMPLETED"
    ],
  "webhookEndpointInfo" : {
    "webhookEndpointId": "e6a238bc-1c67-463c-992c-9edc9ba637a7",
    "domainPrefix": "callback-prod",
    "urlSuffix": "agreement_12_19_2023_1"
  }
}

Replace the value for the following attributes with the correct values:

Attribute	Description
name	Name of the webhookEndpoint resource that you want to create. It’s length cannot be more than 255 characters.
scope	Scope of webhook. This attribute can’t be modified in PUT request. The possible values are ACCOUNT, GROUP, USER or RESOURCE.
state	The state in which the webhook should be created. The possible values are ACTIVE, INACTIVE and DELETED.
webhookSubscriptionEvents	Any valid Event(s) that a webhook would need to be notified.
webhookEndpointId	The webhookEndpointId that to be associated with this webhook.
domainPrefix	Optional URL subdomain value. This value will be used to replace the first wildcard (*).
urlSuffix	Optional Url Suffix to append to the WebhookEndpointId. This value will be used to replace the wildcard (*) at the end.

You will get the following response containing the id of the webhook created:

{
    "id": "fe4880d0-4e16-4964-b5ab-07b06d30a430"
}

Once the webhook is configured with OAuth 2.0 (webhookEndpointId), all future webhook notifications (associated with respective scope) will include the access_token provided by the authorization server, as shown below.

Note

Note the addition of a new value “authorization” under the requestHeaders. This will be included with the remaining headers from before.

webhookNotificationPayload

{
    "method": "POST",
    "url": "/postWebhooksPublish?guid=preview_na1_webhook_12_20_2023_1",
    "requestBody": "{\"webhookId\":\"fe4880d0-4e16-4964-b5ab-07b06d30a430\",\"webhookName\":\"preview_na1_webhook_12_20_2023_1\",\"webhookNotificationId\":\"0364c683-4fbd-4f21-8c80-9a5aa9e2c9e0\",\"webhookUrlInfo\":{\"url\":\"https://callback-prod.yourDomain.com/webhook?agreementId=agreement_12_19_2023_1\"},\"webhookScope\":\"USER\",\"webhookNotificationApplicableUsers\":[{\"id\":\"CBJCHBCAABAAR17L9fNP9kJcZHy759YawVx-pR-aqpf2\",\"email\":\"some-user@yourDomain.com\",\"role\":\"SENDER\",\"payloadApplicable\":true}],\"event\":\"AGREEMENT_ACTION_COMPLETED\",\"eventDate\":\"2023-12-21T00:09:24Z\",\"eventResourceType\":\"agreement\",\"participantRole\":\"SIGNER\",\"actionType\":\"ESIGNED\",\"participantUserId\":\"CBJCHBCAABAAR17L9fNP9kJcZHy759YawVx-pR-aqpf2\",\"participantUserEmail\":\"some-user@yourDomain.com\",\"actingUserId\":\"CBJCHBCAABAAR17L9fNP9kJcZHy759YawVx-pR-aqpf2\",\"actingUserEmail\":\"some-user@yourDomain.com\",\"initiatingUserId\":\"CBJCHBCAABAAR17L9fNP9kJcZHy759YawVx-pR-aqpf2\",\"initiatingUserEmail\":\"some-user@yourDomain.com\",\"agreement\":{\"id\":\"CBJCHBCAABAA6z_Rj994soFPUzj-COPTH62KP4d1Leh3\",\"name\":\"sample_1page_12_20_23_1\",\"status\":\"SIGNED\"}}",
    "clientId": "CBJCHBCAABAAhdTfTbSnTtEqZf_cLHgqnXwNqqucWvWa",
    "time": "Thu Dec 21 2023 00:09:57 GMT+0000 (Coordinated Universal Time)",
    "requestHeaders": {
      "host": "callback-prod.yourDomain.com",
      "accept": "application/json,application/json",
      "accept-charset": "UTF-8",
      "authorization": "bearer HereIsYourSuperSecretAccessToken",
      "x-adobesign-clientid": "CBJCHBCAABAAhdTfTbSnTtEqZf_cLHgqnXwNqqucWvWa",
      "user-agent": "AdobeSign",
      "content-type": "application/json",
      "traceparent": "00-aba78a6cf1c77cb59bf99c2d15168de8-d7d50a348ff58816-00",
      "uber-trace-id": "aba78a6cf1c77cb59bf99c2d15168de8:d7d50a348ff58816:0:0",
      "content-length": "1078",
      "x-forwarded-for": "35.168.147.202",
      "x-forwarded-proto": "https",
      "x-envoy-external-address": "35.168.147.202"
    }
  }