Webhooks provide an event-based notification mechanism that you can use to observe direct changes in individual objects in your project. You can specify filters to make sure you’re notified only about the objects and events you want. With webhooks, you can integrate Kontent.ai with other apps and automate your processes.
(Optional) In Settings > Headers, specify custom headers as key-value pairs to send along with the webhook notification.
In Triggers > Published or preview, select whether the webhook is triggered by changes in Published data or Preview data.
In Triggers > Events, select which events will trigger the webhook.
If you select All events, the webhook gets triggered by any currently available events.
If you select Specific events, the webhook gets triggered only by the events you select and can be limited to specific objects by filters.
Click Save.
The webhook sends a notification to the specified URL address whenever an event occurs. Unsuccessful notification deliveries are retried as per the retry policy.Because content changes are processed dynamically based on load, the notifications may sometimes come in batches. It can take up to a few minutes to receive a notification after a webhook is triggered.
Order of the received notificationsBy default, the notifications are delivered in the order they were created. In rare cases, the deliveries might not follow chronological order. If you need to ensure chronological order, refer to the timestamp in the webhook notification’s last_modified property.
Validate received notifications
Once you start receiving webhook notifications to your endpoints, make sure to validate the notifications to ensure the notifications come from Kontent.ai and not from someone else.Each webhook notification comes with the X-Kontent-ai-Signature HTTP header. This reserved header contains a checksum of the webhook payload. Specifically, the X-Kontent-ai-Signature value is a base64-encoded hash generated using an HMAC-SHA-256 with the webhook’s secret key.You can find the webhook's Secret key in Kontent.ai > Environment settings > Webhooks > Your webhook > Settings > Secret. The secret is unique for each webhook.To verify the received notification, use the raw JSON body of the webhook payload and the generated webhook Secret as the secret for the HMAC function. Once you generate a hash, compare the hash value with the X-Kontent-ai-Signature header value.
No code sample for this language yet. Try selecting another language at the top.
Get the latest content
After you verify a received notification, you might want to request the latest content. By default, Delivery API serves stale content (provided it’s cached by the CDN) while fetching the latest content to minimize wait time.To request the latest content, send a request to Delivery API with the X-KC-Wait-For-Loading-New-Content header set to true. The header tells the API to wait while fetching content if the requested content has changed since the last request.
Kontent.ai sends webhook notifications as POST requests to your webhook URL. The payload of the JSON notifications tells you which object changed and due to which event.For example, when a content item is published, the related webhook payload can look like this:
The notification includes only the directly modified object. For example, when a content type changes, you get a notification about the content type. The notification doesn't include the content items based on the content type. This helps keep the payload size small, even for events affecting thousands of objects.
Data object
The data object contains metadata information that identifies a specific object in your environment. This object can be an asset, content item, content type, language, or taxonomy group.For all object types, the data object specifies the id, name, codename, and last_modified properties of the modified object. For content items, there's additional information about the item.
collection (string): The codename of the content item's collection.
workflow (string): The codename of the content item's workflow.
workflow_step (string): The codename of the content item's workflow step.
language (string): The codename of the content item's language.
type (string): The codename of the content item's content type.
last_modified (string): The object's last modification date and time in ISO-8601 format (YYYY-MM-DDTHH:MM:SSZ) in UTC.
You can use the metadata information in the data object to retrieve the updated object via APIs.
Message object
The message object gives you context for the change. It tells you where the change occurred and due to which event. An event is a combination of an action performed on an object.
environment_id (string): The environment’s internal ID.
object_type (string): Identifies the type of the object that was affected.
action (string): Specifies what happened to the object.
action_context (object): Specifies additional information about the object, such as the content item’s previous workflow state. This property is only present when action is workflow_step_changed.
delivery_slot (string): Specifies whether the change occurred in preview data or published data.
You use the information from the message object to filter webhook notifications in your apps.
Webhook headers
Each webhook notification comes with a set of reserved HTTP headers and can optionally include up to 10 custom HTTP headers. HTTP headers are key: value pairs where the key is case insensitive and the value can be case sensitive depending on the header.
Reserved headers
The following reserved headers are included in every webhook notification. The reserved headers cannot be modified with custom headers.
host (string): The URL to which the webhook notification was sent.
content-length (integer): The size of the payload body in bytes.
x-kontent-ai-signature (string): The checksum of the payload body. Use it to verify notification authenticity.
request-context (string): The internal context of the webhook notification.
request-id (string): The internal identifier of the webhook notification.
traceparent (string): The internal trace information of the webhook notification.
content-type (string): The media type of the webhook payload. Kontent.ai webhook notifications come with the content-type header set to application/json; charset=utf-8.
Custom headers
When creating webhooks, you can specify your own custom headers. This is useful whenever you need to add extra information to your notifications. For example, to authenticate against your endpoint, specify metadata to pass through your firewall, or add context to integrations consuming the notifications.The custom header values are encrypted before they are stored in Kontent.ai. This means the header values are visible only to you.
Rules for custom headers
When adding custom headers, keep in mind the following limitations:
The header key cannot start with the x-kontent-ai prefix.
The header key must fit within 200 characters.
The header key can contain only alphanumeric characters (a-z, A-Z, and 0-9) and the special characters - and _.
The header value must fit within 2,000 characters.
The header value can contain only alphanumeric characters (a-z, A-Z, and 0-9) and the following special characters: _ :;.,\/"'?!(){}[]@<>=-+*#$&`|~^%.
If the webhook specifies multiple headers with the same key, their values are grouped in this format: reusedKey: value1, value2, value3.
Webhook triggers and events
Preview data vs. published data
Webhooks can specify events for assets, content items, content types, languages, and taxonomy groups. Each webhook can focus on changes either in the preview data or published data, not both.
Assets, content types, languages, and taxonomies are the same in preview and published data.
Content items might differ between their latest and published versions. Different content item events are available for preview data vs. for published data.
Asset events
The asset events inform you about changes related to your assets.
The content item events inform you about changes related to your content items and their variants. You can filter the content item events by collections, content types, and languages.Different sets of events are available for published and preview data.
Example: JSON payload for the workflow_step_changed content item event when a published item is unpublished. For workflow step change events, the payload contains information about the previous workflow and workflow step.
The content type events inform you about the changes made to your content types. You can filter the content type events to changes made in specific content types.
Language events inform you about the changes made in the localization settings. You can filter the language events to changes made in specific languages.
Event
Occurs when
object_type
action
Language created
Creating or activating a language
language
created
Language updated
Renaming a language
Changing a language codename
Changing a language fallback
language
changed
Language deleted
Deactivating a language
language
deleted
Example: JSON payload for the deleted language event when a language is deactivated.
Taxonomy events inform you about the changes made to your taxonomy groups and their terms. You can filter the taxonomy events to changes made in specific taxonomy groups.
Event
Occurs when
object_type
action
Taxonomy group created
Creating a taxonomy group
taxonomy
created
Taxonomy group metadata changed
Changing a taxonomy group codename
Renaming a taxonomy group
taxonomy
metadata_changed
Taxonomy group deleted
Deleting a taxonomy group
taxonomy
deleted
Taxonomy term created
Creating a taxonomy term
taxonomy
term_created
Taxonomy term changed
Changing a taxonomy term codename
Renaming a taxonomy term
taxonomy
term_changed
Taxonomy term deleted
Deleting a taxonomy term
taxonomy
term_deleted
Taxonomy terms moved
Reordering taxonomy terms in a taxonomy group
taxonomy
terms_moved
Example: JSON payload for the term_created taxonomy event when a new taxonomy term is added.
The notification delivery is successful if your application responds with a 20X HTTP status code. Any other status code or a request timeout, which occurs after 60 seconds, will result in repeated notification delivery.On the first unsuccessful delivery, Kontent.ai tries to send the notification again in 1 minute. If the delivery is unsuccessful, the delay between resending the notification increases exponentially to a maximum of 1 hour. The delay intervals are 1, 2, 4, 8, 16, 32, and 60 minutes. When the delay reaches 60 minutes, Kontent.ai tries to deliver the notification every hour for up to 3 days, after which the notification is removed from the queue.All notifications are delivered in the order they were created. For example, if a notification is successfully delivered after 4 minutes, the notifications created after it will follow in the original order.By default, the notifications are delivered in the order they were created. For example, if a notification is successfully delivered after 4 minutes, the notifications created after it will follow in the original order.
Email notifications
If there’s a problem with webhook delivery, users with the Manage development settingspermission get an email in these cases:
Notification delivery has been repeatedly failing for 1 hour. This email is sent only once for each active webhook.
Notification delivery has been repeatedly failing for 3 days. After 3 days, the notification won’t be delivered again.
Notification delivery was successful after several failed attempts. This email is only sent if you previously received an email notification about a failed delivery.
Debug webhooks
In Environment settings > Webhooks, you can find a list of your webhooks and their health statuses.
Ready for message – appears for newly created webhooks before any change to published content has been made (so no notification has been sent).
Working – appears for webhooks that have properly delivered notifications.
Failing – appears for webhooks that have not been successfully delivered. The webhook URL returned a response other than a 20X. These webhook notifications are still being sent based on the retry policy. If you’ve issued a fix and want to reset the retry policy, you can reset the webhook.
Dead – appears for webhooks where notification delivery has repeatedly failed, and no notifications have been accepted for 7 days. After 7 days, no more notifications will be sent, and all notifications waiting to be sent will be deleted. You can revive a dead webhook by resetting it.
Find information about your webhooks
For more information about each webhook, click . You’ll find a list of all notifications from the last 3 days, sorted from newest to oldest.You can filter the list to show everything, only failures (at any time in sending the message) or only active failures (where the last response was a failure). Click Refresh to reload the list.Each notification in the list shows:
The number of times the delivery has been attempted.
A button to view the most recent response.
In the window that pops up, use the button to copy the response to the clipboard.
The date and time when the most recent delivery attempt was made.
Reset and revive webhooks
If your webhook is failing or dead, you can reset it. Resetting a webhook means that Kontent.ai attempts to resend the last failed notification, effectively resetting the webhook’s retry policy.
In Kontent.ai, go to Environment settings > Webhooks.
For a failing or dead webhook, click Reset.
Disable and enable webhooks
When you disable a webhook, the webhook stops sending notifications and deletes any unsent notifications. Disabled webhooks ignore their triggers and don’t create any new notifications.For example, if you plan to change your content model, you might want to disable your webhooks first and then adjust your app to the new content model. Disabling webhooks also helps if you plan to release hundreds or thousands of content items in a short amount of time.
In Kontent.ai, go to Environment settings > Webhooks.
Click a webhook to open its details.
Click Disable.
After you enable the webhook back, the webhook is ready to send new notifications whenever content changes.
Outbound IP addresses
If your application runs behind a firewall, you might need to add rules for specific IP addresses so that your app can receive webhook notifications.Kontent.ai sends webhook notifications from the following IP addresses: