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.

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:

  • the label. This is just used to make it easier to identify the webhook in the list
  • the webhook-events that it wants to subscribe to
  • the URL that will be notified when one of these events occurs. This is referred to as the "webhook handler"

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.

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.

Webhook secret

When a webhook is created, Dynamic Content will automatically generate a 128 character secret that is known only to the developer. This secret is used to verify that the body sent to the webhook handler has not been tampered with in transit. A hash is generated from the secret and the request body, encoded and sent in the "X-Amplience-Webhook-Signature" header that is included in the POST request sent to the webhook handler. The developer can then decode this header and compare the hash with the value generated from the received request body and the secret they have stored for this webhook.

See the Dynamic Content Management SDK for an example of how to verify the webhook signature.

To make it easier to store the secret for later use, click the Copy button- the second icon to the right of the secret. You can regenerate the secret by clicking the refresh icon or replace the generated secret with your own value.

Available webhook-events

  • Edition - scheduled: an edition is scheduled

  • Edition - unscheduled: an edition is unscheduled

  • Edition - published: a scheduled edition is published (on its start date)

  • Content item - created: a new content item is created in the production view

  • Content item - updated: a content item is updated. This is triggered when any change is made to the content item

  • Snapshot - published: a snapshot of a content item is published. This is triggered when a content item is published from the production view, or an edition containing a snapshot is published

  • Content item workflow - updated: a content item's status has been updated

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.

Webhook history
Webhook history

To view the POST request sent by Dynamic Content to the webhook URL, click the "View request" button.

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.

An example webhook request
An example webhook request

Click "View response" to view the response sent back by the webhook. 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.

An example webhook response
An example webhook response

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

results matching ""

    No results matching ""