diff --git a/gatsby-config.js b/gatsby-config.js index 99589854f..89836abf2 100644 --- a/gatsby-config.js +++ b/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' diff --git a/src/pages/overview/pdf-accessibility-auto-tag-api/gettingstarted.md b/src/pages/overview/pdf-accessibility-auto-tag-api/gettingstarted.md index 12b689142..9c6a28b27 100644 --- a/src/pages/overview/pdf-accessibility-auto-tag-api/gettingstarted.md +++ b/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}}' ``` + +
+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 documentation. +
+ ## 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`. diff --git a/src/pages/overview/pdf-electronic-seal-api/gettingstarted.md b/src/pages/overview/pdf-electronic-seal-api/gettingstarted.md index 3bb8e0f6f..fe46474b7 100644 --- a/src/pages/overview/pdf-electronic-seal-api/gettingstarted.md +++ b/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}}' ``` + +
+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 documentation. +
+ ## 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`. diff --git a/src/pages/overview/pdf-extract-api/gettingstarted.md b/src/pages/overview/pdf-extract-api/gettingstarted.md index 9f2eb273c..5d7a8be99 100644 --- a/src/pages/overview/pdf-extract-api/gettingstarted.md +++ b/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}}' ``` + +
+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 documentation. +
+ ## 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`. diff --git a/src/pages/overview/pdf-services-api/gettingstarted.md b/src/pages/overview/pdf-services-api/gettingstarted.md index 7700e7140..fd34895b3 100644 --- a/src/pages/overview/pdf-services-api/gettingstarted.md +++ b/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}}' ``` + +
+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 documentation. +
+ ## 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`. diff --git a/src/pages/overview/pdf-services-api/howtos/webhook-notification.md b/src/pages/overview/pdf-services-api/howtos/webhook-notification.md new file mode 100644 index 000000000..7dd7b21d6 --- /dev/null +++ b/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": "", + ...., + ///REST API Operation related details + .... + + "notifiers": [ + { + "type": "", + "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": "", + ...., + ///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": "", + "statusResponse": { + "status": "done", + "asset": { + "metadata": { + "type": "application/pdf", + "size": 318974 + }, + "downloadUri": "" + } + } +} +``` + +#### In case Job completes with Failure +In case of failed job completion, the following **callback payload** will be sent to callback url: +```json +{ + "jobID": "", + "statusResponse": { + "status": "failed", + "error": { + "code": "", + "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" +} +``` + +
+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. +
+ +## 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. diff --git a/src/pages/overview/releasenotes.md b/src/pages/overview/releasenotes.md index f016d1bc8..fc28e16d7 100644 --- a/src/pages/overview/releasenotes.md +++ b/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 | diff --git a/src/pages/resources/openapi.json b/src/pages/resources/openapi.json index a6e644df5..f7ef37dc2 100644 --- a/src/pages/resources/openapi.json +++ b/src/pages/resources/openapi.json @@ -8350,6 +8350,9 @@ }, "documentLanguage": { "$ref": "#/components/schemas/documentLanguage" + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "default": { @@ -8357,7 +8360,19 @@ }, "example": { "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718", - "documentLanguage": "en-US" + "documentLanguage": "en-US", + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "required": [ "assetID" @@ -8432,12 +8447,27 @@ }, "ocrLang": { "$ref": "#/components/schemas/exportOCRLang" + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718", "targetFormat": "docx", - "ocrLang": "en-US" + "ocrLang": "en-US", + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "additionalProperties": false }, @@ -8524,12 +8554,27 @@ "listOfPageImages", "zipOfPageImages" ] + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718", "targetFormat": "jpeg", - "outputType": "listOfPageImages" + "outputType": "listOfPageImages", + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "additionalProperties": false }, @@ -8631,6 +8676,9 @@ "figures" ] } + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { @@ -8645,6 +8693,18 @@ "renditionsToExtract": [ "tables", "figures" + ], + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } ] }, "additionalProperties": false @@ -8691,6 +8751,9 @@ ] } } + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { @@ -8700,7 +8763,19 @@ "pageLayout": { "pageWidth": 11, "pageHeight": 8.5 - } + }, + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "additionalProperties": false }, @@ -8795,6 +8870,9 @@ }, "required": ["assetID"] } + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { @@ -8817,6 +8895,18 @@ } ] } + ], + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } ] }, "required": [ @@ -8922,11 +9012,26 @@ "MEDIUM", "HIGH" ] + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718", - "compressionLevel": "LOW" + "compressionLevel": "LOW", + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "required": [ "assetID" @@ -8986,10 +9091,25 @@ "assetID": { "description": "A file assetID. For more details click here .", "type": "string" + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { - "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718" + "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718", + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "required": [ "assetID" @@ -9043,12 +9163,27 @@ "searchable_image", "searchable_image_exact" ] + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718", "ocrLang": "en-US", - "ocrType": "searchable_image" + "ocrType": "searchable_image", + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "required": [ "assetID" @@ -9128,6 +9263,9 @@ ] } ] + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { @@ -9154,6 +9292,18 @@ ] } } + ], + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } ] }, "required": [ @@ -9351,6 +9501,9 @@ "COPY_CONTENT" ] } + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { @@ -9363,6 +9516,18 @@ "permissions": [ "PRINT_HIGH_QUALITY", "EDIT_CONTENT" + ], + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } ] }, "required": [ @@ -9478,11 +9643,26 @@ "password": { "description": "Password required for removing security/permissions from the PDF document.", "type": "string" + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718", - "password": "XXXXX" + "password": "XXXXX", + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "required": [ "assetID", @@ -9559,6 +9739,9 @@ "$ref": "#/components/schemas/pageRanges" } ] + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { @@ -9570,7 +9753,19 @@ "end": 10 } ] - } + }, + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "required": [ "assetID", @@ -9603,6 +9798,9 @@ "fragments": { "description": "Specifies the Fragments JSON object or a JSON array to resolve fragments in the document template. To know more about fragments use-case in document generation and document templates, please see the documentation.", "type": "object" + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { @@ -9631,7 +9829,19 @@ 300 ], "photograph": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP88h8AAu0B9XNPCQQAAAAASUVORK5CYII=" - } + }, + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "required": [ "assetID", @@ -9898,6 +10108,9 @@ }, "sealOptions": { "$ref": "#/components/schemas/sealOptions" + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { @@ -9942,7 +10155,19 @@ "SEAL_IMAGE" ] } - } + }, + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "additionalProperties": false }, @@ -10147,6 +10372,23 @@ } } }, + "notifiers": { + "description": "Specifies the notifiers to be invoked on the completion of job. To know more about notifiers, please see the documentation.", + "type": "array", + "items": { + "properties": { + "type": { + "description": "Specifies the notifier type. Currently supported value is \"CALLBACK\" only.", + "type": "string" + }, + "data": { + "description": "Specifies the data needed to invoke the notifier.", + "type": "object" + } + }, + "required": ["type", "data"] + } + }, "AutoTagPDF": { "title": "Internal", "description": "Parameter for Accessibility Auto-Tag operation.", @@ -10168,12 +10410,27 @@ "description": "Boolean specifying whether to generate excel report.", "type": "boolean", "default": false + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718", "shiftHeadings": false, - "generateReport": false + "generateReport": false, + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "additionalProperties": false }, @@ -10195,12 +10452,27 @@ "pageEnd": { "description": "The parameter allows for the specification of the ending page for the accessibility check. If \"pageEnd\" is not provided, the last page is considered the default pageEnd. It should be greater than equal to 1.", "type": "number" + }, + "notifiers": { + "$ref": "#/components/schemas/notifiers" } }, "example": { "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718", "pageStart": 1, - "pageEnd": 5 + "pageEnd": 5, + "notifiers": [ + { + "type": "CALLBACK", + "data": { + "url": "https://dummy.callback.org/", + "headers": { + "x-api-key": "dummykey", + "access-token": "dummytoken" + } + } + } + ] }, "additionalProperties": false }, @@ -11541,32 +11813,32 @@ } }, "ElectronicSealPDFDone" : { - "title": "done", - "description": "Response in case of 'done' status", - "type": "object", - "properties": { - "status": { - "description": "Job Status", - "type": "string", - "enum": [ - "done" - ] - }, - "asset": { - "$ref": "#/components/schemas/responseAsset" - } + "title": "done", + "description": "Response in case of 'done' status", + "type": "object", + "properties": { + "status": { + "description": "Job Status", + "type": "string", + "enum": [ + "done" + ] }, - "example": { - "status": "done", - "asset": { - "metadata": { - "type": "application/pdf", - "size": 200791 - }, - "downloadUri": "https://dcplatformstorageservice-dev-us-east-1.s3-accelerate.amazonaws.com/6bb12fd8-3233-4340-916b-4835917857be?X-Amz-Security-Token=FwoGZXIvYXdzEE0aDOLg7PFwVB1bjEMxQCLTAe3pjf%2Fgl2Pj%2FcjOaY%2BHfduju9SXTp1Pn8C4GapIXm%2F8tuR4cGPYGC0goU21qZxCq9R%2F8z2bOmB2EL%2BZrhbPLbaNcpzf5Vud%2B3Bmn61MEJiBdU%2BhZqasX5YhVxdnzhfpl5KfKeq2kwROVMqJcyHGdxw5h0%2Bi0sD2I8sqkbPmnBi0WOtYNwz7TQq42oe8W5KYHpq6WMya9OQgx0u7qg0inYwBnQu5UQ9NJJQY2MSU11IuZ0uE%2B%2FNAPuq3VfEIn3txK%2FFfIxGz9%2BInehhHroKjBFULzy0olY2rlwYyLQDwHHr2eyuy%2BaoGVaq%2BSUNH8T0OKIicbbZfQ5wjF0hK2FzVXwfebtDG4qq%2BiA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220803T190422Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=ASIAU5PA7W47AH3PA2JV%2F20220803%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=5d8c3f421c68c009b4471919a319ba460495c72afe51674d23266bc124fe9a56", - "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718" - } + "asset": { + "$ref": "#/components/schemas/responseAsset" + } + }, + "example": { + "status": "done", + "asset": { + "metadata": { + "type": "application/pdf", + "size": 200791 + }, + "downloadUri": "https://dcplatformstorageservice-dev-us-east-1.s3-accelerate.amazonaws.com/6bb12fd8-3233-4340-916b-4835917857be?X-Amz-Security-Token=FwoGZXIvYXdzEE0aDOLg7PFwVB1bjEMxQCLTAe3pjf%2Fgl2Pj%2FcjOaY%2BHfduju9SXTp1Pn8C4GapIXm%2F8tuR4cGPYGC0goU21qZxCq9R%2F8z2bOmB2EL%2BZrhbPLbaNcpzf5Vud%2B3Bmn61MEJiBdU%2BhZqasX5YhVxdnzhfpl5KfKeq2kwROVMqJcyHGdxw5h0%2Bi0sD2I8sqkbPmnBi0WOtYNwz7TQq42oe8W5KYHpq6WMya9OQgx0u7qg0inYwBnQu5UQ9NJJQY2MSU11IuZ0uE%2B%2FNAPuq3VfEIn3txK%2FFfIxGz9%2BInehhHroKjBFULzy0olY2rlwYyLQDwHHr2eyuy%2BaoGVaq%2BSUNH8T0OKIicbbZfQ5wjF0hK2FzVXwfebtDG4qq%2BiA%3D%3D&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220803T190422Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=ASIAU5PA7W47AH3PA2JV%2F20220803%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=5d8c3f421c68c009b4471919a319ba460495c72afe51674d23266bc124fe9a56", + "assetID": "urn:aaid:AS:UE1:23c30ee0-2c4d-46d6-87f2-087832fca718" } + } }, "failed": { "description": "Response in case of 'failed' status", @@ -11609,4 +11881,3 @@ } } } -