Webhooks

A webhook is a way for a third party system to request to be notified when a certain action occurs in Dynamic Content. For example, an e-commerce system might need to know when an edition is scheduled to allow it to retrieve the slots and content that the edition contains. Similarly it would also need to be notified when that edition is unscheduled.

Developers create webhooks that subscribe to certain specified "webhook events" generated by Dynamic Content. These webhook events usually correspond to an action performed by the user such as creating or editing content, or scheduling editions. Webhooks are associated with a single Dynamic Content hub.

Webhooks provide a way for developers to integrate their software with Dynamic Content, particularly useful if you're developing an ecommerce integration, for example.

For details of how you can create webhooks with filters, custom payloads and custom headers see customizable webhooks.

Webhook management user interface

To create a new webhook or manage an existing one, choose "Webhooks" from the Development menu in the Dynamic Content app. You will need the appropriate developer permissions to create and manage webhooks, so if the Webhooks menu item is not shown, then contact your Customer Success Manager.

The webhook management UI is accessed from the development menu
The webhook management UI is accessed from the development menu

The webhooks screen will be displayed listing all the webhooks that have been added to the hub. If no webhooks are set up, then you will see a screen as shown below.

Click the "Add webhook" button to add a new webhook.

Click the Add webhook button to add a webhook
Click the Add webhook button to add a webhook

Creating a webhook

When creating a webhook, you specify a label, the webhook-events that it subscribes to and the URL that will be notified when one of these events occurs.

When Dynamic Content generates an event that a webhook subscribes to, it will trigger the webhook and send a HTTP POST request to the webhook URL. The request will include a "payload" containing information that the webhook handler will process. You can view the payload and headers sent with each webhook request, together with the response, in the webhook history.

The available webhook events will be shown in the "Events that trigger this webhook" section. Choosing which webhook-events that your webhook handles depends on the structure of your code and the user actions that you are interested in. In the "Example integration" webhook, the webhook handler will be notified when a new content item is created or an existing item is updated.

For details of the supported webhook events, how they are triggered and the payload for each webhook event, go to the webhook payload page.

You can also choose to include filters, custom headers and custom payloads. See the customizable webhooks page for more details.

Creating a webhook with label, URL and supported events
Creating a webhook with label, URL and supported events

When you've configured the webhook, click the "Save" button. Then click "Back" to return to the webhooks screen. The newly created webhook will be displayed in the list, together with any other webhooks that have been added to this hub.

Viewing, editing and deleting webhooks

To edit a webhook, either click its label to open the editing screen or right click its contextual menu as shown in the image below. From this menu you can activate, deactivate or delete the webhook. Deactivated webhooks will not be triggered.

The newly created webhook is added to the list
The newly created webhook is added to the list

Recent webhook history

When a webhook is triggered, the information about each POST request sent to the webhook URL, and the response, is listed in the "Recent deliveries" section of the webhook information window. Each time the webhook is triggered an entry will be added to the list.

The list will show a delivery ID, a unique value generated each time a request is sent, and the status code that was returned in the response.

Click view details to view the webhook request and response
Click view details to view the webhook request and response

To view the POST request sent by Dynamic Content to the webhook URL, together with the response, click "View details".

An example of the request sent to a webhook that accepts the content updated webhook-event is shown below. The request consists of headers and a body. The headers include the webhook signature and the body includes the payload. In this example the webhook handler was triggered by the user updating a content item, so the payload includes information about the updated item such as the current version and the creation and modification date.

In this example we can see that the webhook request was handled successfully with a response code of 200 and no response body was returned.

In many cases a webhook handler will request that another app performs a certain action when the webhook is triggered. If this app returns an error, you can include the error in the response body so that it will be logged in the webhook history.

The request and response are shown on one screen
The request and response are shown on one screen

Errors and retries

When an error occurs, such as a 404 if the webhook URL can not be found, then multiple delivery attempts are shown in the webhook history under the same delivery ID. In the example below, the webhook URL cannot be found. Dynamic Content will retry up to 18 times within a total of 12 hours. If the webhook handler does not respond after this time, then it will be deactivated.

Dynamic Content will retry the webhook if an error occurs
Dynamic Content will retry the webhook if an error occurs

Our webhook retry policy is based on REST Hooks.

Customizable webhooks

Webhook payloads

results matching ""

    No results matching ""