Webhook FAQs

Common questions

• What is the maximum custom payload output size?
• What is the maximum size of the handlebars included in the custom payload?
• What is the webhook secret and what is it used for?
• Which IP addresses should I whitelist to allow requests from Amplience webhooks?
• Can I monitor the webhook activity log for failures?
• What events can trigger a webhook?
• How can I configure a webhook to trigger for a specific content type?
• How long are the webhook logs retained?

Search indexes

• How can I find which content items failed to index?

Common questions

What is the maximum custom payload output size?

For a given webhook event, the maximum size of the output is 200 KB. When the custom payload is processed, if the resulting output is > 200 KB then an error will be generated. An example of the error is shown below.

What is the maximum size of the handlebars included in the custom payload?

The maximum size of the handlebars template that defines the custom payload is 5 KB.

What is the webhook secret and what is it used for?

The webhook secret is generated automatically when you create a new webhook. It's used to verify that the webhook originated in Dynamic Content and that the body sent to the webhook URL has not been tampered with in transit. You will save the secret and use it for later verification.

When the webhook is invoked, a hash is generated from the secret and the request body and sent in the "X-Amplience-Webhook-Signature" included with the webhook request. You can then compare this hash with the value generated from the saved webhook secret.

Which IP addresses should I whitelist to allow requests from Amplience webhooks?

The range of IP addresses from which webhooks will be sent is as follows (using CIDR notation):

34.242.23.128/32
63.32.123.5/32
52.19.110.60/32

If you are referencing a Virtual Staging Environment (VSE) in your custom payload- using the withDeliveryHelper, for example, then you will need to ensure that these IP addresses are included in your VSE white list.

Can I monitor the webhook activity log for failures?

You can access the webhook activity log via our API so you could potentially retrieve this data on a regular basis and search the response for specific failures. The endpoint you need is list requests for a webhook.

What events can trigger a webhook?

Webhooks will be triggered by an action performed in Dynamic Content. When you create a webhook you can choose one or more of the following triggers:

• Edition scheduled, unscheduled or published
• Snapshot published (this is triggered when a content item is published or a snapshot is published when an edition is published. The payload is different when triggered from a content item or edition).
• Content item created or updated
• Content item workflow updated
• Content item assignee changed

For more details about each webhook trigger and the payload sent to your webhook see the webhook payloads page.

How can I configure a webhook to trigger for a specific content type?

You can use filters to only send a webhook request when certain conditions are met, for example if an item is of a specified content type. Filters are specified in JSON Path format and use the fields of the webhook payload.

For example, for a webhook triggered on snapshot published, you set the JSON Path field to $.payload.rootContentItem.contentTypeUri and the value field to the schema ID you are matching against, for example https://example.com/myschema. You can also included multiple values in a filter and multiple filters.

If you're using content item created or updated as the trigger, then you'd set the JSON Path field to $.payload.body._meta.schema as shown in the example below. In this example, the webhook request will only be sent if a content item created from the https://example.com/myschema is created or updated.

See filters for more details.

How long are the webhook logs retained?

The webhook logs are available to view in the activity log for 30 days.

Search indexes

How can I find which content items failed to index?

To work out which content item caused a request to fail you need to look at the request body in the webhook activity log. This contains an escaped version of our standard webhook payload. For a production index the webhook is triggered on snapshot published and the body will include payload.rootContentItem where you can find the ID and label of the relevant content item.

For staging indexes, where the content items are indexed when an item is created or updated, the content item id can be found in payload.id.

You can paste either content item id or name into the search field in Dynamic Content to find the content item referenced in the webhook payload.