webhook notification support

gatsby-config.js

@@ -193,6 +193,10 @@ module.exports = {
                                 title: 'External Storage for APIs',
                                 path: 'overview/pdf-services-api/howtos/pdf-external-storage-sol.md'
                             },
+                            {
+                                title: 'Webhook Notification for APIs',
+                                path: 'overview/pdf-services-api/howtos/webhook-notification.md'
+                            },
                             {
                                 title: 'Create PDF',
                                 path: 'overview/pdf-services-api/howtos/create-pdf.md'

src/pages/overview/pdf-accessibility-auto-tag-api/gettingstarted.md

@@ -86,6 +86,11 @@ curl --location -g --request GET 'https://pdf-services.adobe.io/operation/compre
 --header 'x-api-key: {{Placeholder for client id}}'
 ```
 
+<InlineAlert slots="text"/>
+<div>
+Instead of using the status API to check the job status, you have the option to receive job completion notifications through Webhook. For more information, please refer the <a href="../../pdf-services-api/howtos/webhook-notification/">documentation</a>.
+</div>
+
 ## Step 5 : Downloading the asset 
 
 On getting `200` response code from the poll API, you will receive a `status` field in the response body which can either be `in progress`, `done` or `failed`.

src/pages/overview/pdf-electronic-seal-api/gettingstarted.md

@@ -135,6 +135,11 @@ curl --location -g --request GET 'https://pdf-services.adobe.io/operation/electr
 --header 'x-api-key: {{Placeholder for client id}}'
 ```
 
+<InlineAlert slots="text"/>
+<div>
+Instead of using the status API to check the job status, you have the option to receive job completion notifications through Webhook. For more information, please refer the <a href="../../pdf-services-api/howtos/webhook-notification/">documentation</a>.
+</div>
+
 ## Step 8 : Downloading the asset
 
 On getting `200` response code from the poll API, you will receive a `status` field in the response body which can either be `in progress`, `done` or `failed`.

src/pages/overview/pdf-extract-api/gettingstarted.md

@@ -86,6 +86,11 @@ curl --location -g --request GET 'https://pdf-services.adobe.io/operation/compre
 --header 'x-api-key: {{Placeholder for client id}}'
 ```
 
+<InlineAlert slots="text"/>
+<div>
+Instead of using the status API to check the job status, you have the option to receive job completion notifications through Webhook. For more information, please refer the <a href="../../pdf-services-api/howtos/webhook-notification/">documentation</a>.
+</div>
+
 ## Step 5 : Downloading the asset
 
 On getting `200` response code from the poll API, you will receive a `status` field in the response body which can either be `in progress`, `done` or `failed`.

src/pages/overview/pdf-services-api/gettingstarted.md

@@ -85,6 +85,11 @@ curl --location -g --request GET 'https://pdf-services.adobe.io/operation/compre
 --header 'x-api-key: {{Placeholder for client id}}'
 ```
 
+<InlineAlert slots="text"/>
+<div>
+Instead of using the status API to check the job status, you have the option to receive job completion notifications through Webhook. For more information, please refer the <a href="../howtos/webhook-notification/">documentation</a>.
+</div>
+
 ## Step 5 : Downloading the asset
 
 On getting `200` response code from the poll API, you will receive a `status` field in the response body which can either be `in progress`, `done` or `failed`.

src/pages/overview/pdf-services-api/howtos/webhook-notification.md

@@ -0,0 +1,122 @@
+---
+title: Webhook Notification support for Adobe PDF Services APIs | Adobe PDF Services
+---
+# **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](https://developer.adobe.com/document-services/docs/apis/#tag/Create-PDF/operation/pdfoperations.jobstatus) 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](https://developer.adobe.com/document-services/docs/apis/#tag/Create-PDF/operation/pdfoperations.createpdf)** 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](#callback-webhook-usage).
+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](#callback-webhook-usage) section.
+
+### Sample Request Body
+```json
+{
+  "assetID": "<ASSET ID>",
+  ....,
+  ///REST API Operation related details
+  ....
+
+  "notifiers": [
+    {
+      "type": "<NOTIFIER_TYPE>",
+      "data": {
+          //<NOTIFICATION_DATA>
+        }
+      }
+    }
+  ]
+}
+```
+
+## **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
+
+```json
+{
+  "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"
+        }
+      }
+    }
+  ]
+}
+```
+
+### 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:
+```json
+{
+  "jobID": "<JOB ID>",
+  "statusResponse": {
+    "status": "done",
+    "asset": {
+      "metadata": {
+        "type": "application/pdf",
+        "size": 318974
+      },
+      "downloadUri": "<DOWNLOAD URI",
+      "assetID": "<ASSET ID>"
+    }
+  }
+}
+```
+
+#### In case Job completes with Failure
+In case of failed job completion, the following **callback payload** will be sent to callback url:
+```json
+{
+  "jobID": "<JOB ID>",
+  "statusResponse": {
+    "status": "failed",
+    "error": {
+      "code": "<ERROR CODE>",
+      "message": "<ERROR MESSAGE>",
+      "status": 400
+    }
+  }
+}
+```
+
+## Expected Response from the Client
+The client is expected to return the following response payload with an HTTP status code of 200 (OK):
+```json
+{
+  "ack": "done"
+}
+```
+<InlineAlert slots="text"/>
+<div>
+If the response code is not 200 (OK) or the expected payload is not received, it will be considered an error response. In the event of 50 error responses within a 10-minute period, webhook notification support will be temporarily blocked for that client for the next 20 minutes.
+</div>
+
+## Limitations
+1. Webhook notification support is not available for [external storage](https://developer.adobe.com/document-services/docs/overview/pdf-services-api/howtos/pdf-external-storage-sol/) based APIs.
+2. It is not available for [PDFProperties](https://developer.adobe.com/document-services/docs/overview/pdf-services-api/howtos/pdf-properties/) operation.
+2. It is currently not available in SDKs (v3.5.0 and below). Future versions of SDK will include the support of notifiers.

src/pages/overview/releasenotes.md

@@ -173,6 +173,12 @@ Upgrading to the latest SDK should not break existing applications.
 
 ## Change history
 
+### Server Side Release (January, 2024; server side release)
+
+| Change | Language | Description                                                                                                                                                           |
+|--------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| New    | API     | Added support for [Webhook Notification](../pdf-services-api/howtos/webhook-notification/) in all the operations **except** PDF Properties and Accessibility Checker. |
+
 ### 3.5.1 (December, 2023: patch release)
 
 | Change  | Language | Description                                                                      |