Webhook Notification Support for Adobe PDF Services APIs

Adobe PDF Service APIs now offer support for Webhook notifications. Webhooks are designed to facilitate the receipt of job completion notifications. This new feature eliminates the need for clients to manually invoke the GET Status API to obtain job completion status and results. Instead, they will receive automatic notifications containing the job status and result.

To leverage the power of webhooks, clients are required to include the notifiers key in the request body when making a call to the Submit Job API. The notifiers key is designed to receive a list of objects, with each object corresponding to a specific webhook. Each notifier object is composed of two essential fields: type and data. Here, we provide detailed information about these fields and offer a sample request:

1. type: This field specifies the type of notifier to be invoked. Currently, the only supported notifier type is CALLBACK.
2. data: This field contains the data required for the webhook. The specific data may vary depending on the type of notifier in use.

For more information on the CALLBACK notifier, please refer to the Callback Notifier section.

Sample Request Body

{
   "assetID": "<ASSET ID>",
   ....,
   ///REST API Operation related details
   ....

   "notifiers": [
      {
         "type": "<NOTIFIER_TYPE>",
         "data": {
            //<NOTIFICATION_DATA>
         }
      }
      }
   ]
}
CopyCopied to your clipboard
1{
2   "assetID": "<ASSET ID>",
3   ....,
4   ///REST API Operation related details
5   ....
6
7   "notifiers": [
8      {
9         "type": "<NOTIFIER_TYPE>",
10         "data": {
11            //<NOTIFICATION_DATA>
12         }
13      }
14      }
15   ]
16}

Callback Webhook Usage

The callback webhook feature allows the client to receive notifications regarding job completion on an HTTPS URL. To enable this feature, the client is required to create an HTTPS POST URL and share that URL along with the necessary header information in the request. Once the job has been successfully completed, we generate a notification payload that includes information about the job status and the details of the output assets. This payload is then sent via an HTTP POST request to the URL provided by the client.

Parameters for the Notifier Object

When utilizing the callback webhook, the following parameters need to be included within the notifier object:

1. type (Required): This field should always be set to CALLBACK.
2. data (Required): The "data" field contains the following keys:
   • url (Required): This is the HTTPS POST URL created by the user to receive the callback.
   • headers (Optional): This is a map of key-value pairs and represents header-related information required to make the URL call. This field is optional but can be used to provide additional context or authentication for the callback.

Sample Notifier Object

{
   "assetID": "<ASSET ID>",
   ....,
   ///REST API Operation related details
   ....

   "notifiers": [
      {
         "type": "CALLBACK",
         "data": {
            "url": "https://dummy.callback.org/",
            "headers": {
               "x-api-key": "dummykey",
               "access-token": "dummytoken"
            }
         }
      }
   ]
}
CopyCopied to your clipboard
1{
2   "assetID": "<ASSET ID>",
3   ....,
4   ///REST API Operation related details
5   ....
6
7   "notifiers": [
8      {
9         "type": "CALLBACK",
10         "data": {
11            "url": "https://dummy.callback.org/",
12            "headers": {
13               "x-api-key": "dummykey",
14               "access-token": "dummytoken"
15            }
16         }
17      }
18   ]
19}

Callback Payload on HTTPS URL

The notification payload sent to CALLBACK URL is same as that of GET STATUS response along with jobID.

In case Job completes with Success

In case of successful job completion, the following callback payload will be sent to callback url:

{
   "jobID": "<JOB ID>",
   "statusResponse": {
      "status": "done",
      "asset": {
         "metadata": {
            "type": "application/pdf",
            "size": 318974
         },
         "downloadUri": "<DOWNLOAD URI",
         "assetID": "<ASSET ID>"
      }
   }
}
CopyCopied to your clipboard
1{
2   "jobID": "<JOB ID>",
3   "statusResponse": {
4      "status": "done",
5      "asset": {
6         "metadata": {
7            "type": "application/pdf",
8            "size": 318974
9         },
10         "downloadUri": "<DOWNLOAD URI",
11         "assetID": "<ASSET ID>"
12      }
13   }
14}

In case Job completes with Failure

In case of failed job completion, the following callback payload will be sent to callback url:

{
   "jobID": "<JOB ID>",
   "statusResponse": {
      "status": "failed",
      "error": {
         "code": "<ERROR CODE>",
         "message": "<ERROR MESSAGE>",
         "status": 400
      }
   }
}
CopyCopied to your clipboard
1{
2   "jobID": "<JOB ID>",
3   "statusResponse": {
4      "status": "failed",
5      "error": {
6         "code": "<ERROR CODE>",
7         "message": "<ERROR MESSAGE>",
8         "status": 400
9      }
10   }
11}

Expected Response from the Client

The client is expected to return the following response payload with an HTTP status code of 200 (OK):

{
   "ack": "done"
}
CopyCopied to your clipboard
1{
2   "ack": "done"
3}

Note: The webhook notification support is only available in SDKs version 4.x.x and the REST APIs.