Webhooks reference
Webhooks provide an event-based notification mechanism. They let you know about specific changes in your project as they happen. Learn how they work in Kontent.
Table of contents
Events to trigger a webhook
When you create a webhook, you can define specific events that trigger the webhook. These events are usually the result of specific user actions in the Kontent UI. They can be also caused by altering your project via the Management API.
The events are divided in three sections based on the type and purpose of the notifications they trigger. For example, if you need to rebuild your static site for preview purposes, you'll want to use the events under Preview Delivery API triggers. Or if you need to send content for translation after it's been moved to the review step, you'll want to use the events under Management API triggers.
Choose events based on your use case and the API you need to use after receiving the notification. Your project's content is synchronized across Management API, Delivery API, and Delivery Preview API. This is why some of the events may seem as duplicates.
Management API triggers
These events let you subscribe to specific changes to your content in the Management API.
- Workflow step events – triggered when a content item is moved to a specific workflow step.
- Content item events – triggered when a content item is created, deleted, or restored after being deleted, based on your selection.
Delivery API triggers
These events let you subscribe to specific changes to your content in the Delivery API. This API contains only published content.
- Content item events – triggered when a content item is published or unpublished, based on your selection.
- Taxonomy events – triggered when a taxonomy group is created (or updated), deleted, or restored after being deleted, based on your selection.
Publish event vs. Published step event
When you publish content items, first their workflow step changes to Published and then they become publicly available through the Delivery API. These are two separate events – first is the workflow step transition to the Published step event followed by the content item Publish event for the Delivery API. You can subscribe to both events if needed.
Delivery Preview API triggers
These events let you subscribe to specific changes to your content in the Delivery Preview API. This API contains published and unpublished content.
- Content item events – triggered when a content item is created or updated, or deleted, based on your selection.
- Taxonomy events – triggered when a taxonomy group is created or updated, deleted, or restored after being deleted, based on your selection.
Anatomy of webhook notifications
Kontent sends notifications to your webhook URL as POST requests. Every POST request contains a JSON payload and a set of HTTP headers. The JSON payload consists of the Data object with metadata of the changed content and the Message object with details about the origin of the notification.
For example, here's a webhook notification sent as a result of the content item Publish event for the Delivery API.
{ "data": { "items": [ { "id": "e5d575fe-9608-4523-a07d-e32d780bf92a", "codename": "published_article", "language": "en-US", "type": "article" } ], "taxonomies": [] }, "message": { "id": "e1b372a2-1186-4929-b370-904c59f060b7", "project_id": "bf32e7ab-85c3-0073-47b9-90838a8462de", "type": "content_item_variant", "operation": "publish", "api_name": "delivery_production", "created_timestamp": "2020-05-18T10:52:33.1059256Z", "webhook_url": "https://example.com/cache-invalidate" } }{ "data": { "items": [ { "id": "e5d575fe-9608-4523-a07d-e32d780bf92a", "codename": "published_article", "language": "en-US", "type": "article" } ], "taxonomies": [] }, "message": { "id": "e1b372a2-1186-4929-b370-904c59f060b7", "project_id": "bf32e7ab-85c3-0073-47b9-90838a8462de", "type": "content_item_variant", "operation": "publish", "api_name": "delivery_production", "created_timestamp": "2020-05-18T10:52:33.1059256Z", "webhook_url": "https://example.com/cache-invalidate" } }
Data object
The Data object contains metadata of the changed content. For example, consider a change of taxonomy group that's used in multiple published content items. Notification about such change will contain metadata of the changed taxonomy group as well as all the affected content items.
{ "data": { "items": [ { "id": "e113e464-bffb-4fbd-a29b-47991d003732", "codename": "report_for_2019", "language": "en-US", "type": "article" }, { "id": "e113e464-bffb-4fbd-a29b-47991d003732", "codename": "report_for_2020", "language": "en-US", "type": "article" } ], "taxonomies": [ { "id": "4794dde6-f700-4a5d-b0dc-9ae16dcfc73d", "codename": "category" } ] }, "message": { ... } }{ "data": { "items": [ { "id": "e113e464-bffb-4fbd-a29b-47991d003732", "codename": "report_for_2019", "language": "en-US", "type": "article" }, { "id": "e113e464-bffb-4fbd-a29b-47991d003732", "codename": "report_for_2020", "language": "en-US", "type": "article" } ], "taxonomies": [ { "id": "4794dde6-f700-4a5d-b0dc-9ae16dcfc73d", "codename": "category" } ] }, "message": { ... } }
Item objects
Due to the variety of events you can subscribe to, the items
array in the Data object may contain different types of Item objects. The type of the Item objects is never mixed within a single notification.
About the first item in the items
array
When the notification's type
is content_item_variant
and its operation
is archive
, restore
, publish
, or unpublish
, then the first item in the items
array designates the content item that caused the notification to be sent. For example, if the operation is unpublish
, then the first item in the array was unpublished and the other items were affected by this operation.
Item object for content item events
id
(string): The content item's internal ID.codename
(string): The content item's codename.language
(string): The language's codename.type
(string): The content type's codename.
Item object for workflow events
item
(Reference to content item): The content item's ID.language
(Reference to language): The language's ID.transition_from
(Reference to workflow step): The ID of the workflow step the content item was moved from.transition_to
(Reference to workflow step): The ID of the workflow step the content item was moved to.
Taxonomy object
The taxonomies
array in the Data object always contains a single type of object that specifies a taxonomy group.
id
(string): The taxonomy group's internal ID.codename
(string): The taxonomy group's codename.
The taxonomies
array is not present for notifications about workflow step transitions.
Message object
The Message object tells you the origin of the notification. For example, you can see which project the notification came from and what action caused it to be sent.
id
(string): The notification's internal ID.type
(string): The type of the changed data. For more details, see Types and operations.operation
(string): The operation (such as create, upsert, archive, and others) performed on the data. For more details, see Types and operations.api_name
(string): The identifier of the Kontent API that the notification relates to. Possible values aredelivery_production
for the Delivery API,delivery_preview
for the Delivery Preview API, andcontent_management
for the Management API.project_id
(string): The project's ID.webhook_url
(string): A publicly available URL address of your webhook endpoint, for example,https://example.com/cache-invalidate
.created_timestamp
(string): ISO-8601Opens in a new window formatted UTC time and date, for example,YYYY-MM-DDTHH:MM:SSZ
.
"message": { "id": "b357fa9f-15ad-422d-84c7-b6bebc512c50", "project_id": "11a3492b-cd32-0054-51d2-8234ec4244a6", "type": "content_item_variant", "operation": "change_workflow_step", "api_name": "content_management", "created_timestamp": "2019-07-18T15:07:17.6823904Z", "webhook_url": "https://example.com/invalidate-cache" }"message": { "id": "b357fa9f-15ad-422d-84c7-b6bebc512c50", "project_id": "11a3492b-cd32-0054-51d2-8234ec4244a6", "type": "content_item_variant", "operation": "change_workflow_step", "api_name": "content_management", "created_timestamp": "2019-07-18T15:07:17.6823904Z", "webhook_url": "https://example.com/invalidate-cache" }
Want to parse the headers first?
The information from the Message object is also contained in the HTTP headers of the POST request. You can use the headers to preprocess the notifications without examining the payload.
Each HTTP header has the prefix X-KC-Message
. For example, the project_id
property is mirrored by the X-KC-Message-Project-Id
header.
Types and operations
The values of the type
and operation
properties in the Message object tell you what changed in your project and how. The type
property answers the what and the operation
property answers the how.
Here is a list of some of the possible type
and operation
pairs along with descriptions of what changed in each case. More than one event might be triggered for a given type-operation pair.
asset
typeupsert
operation – For one or more assets used in content items, the asset description (alt text) was changed or the asset was replaced.
content_item
typeupsert
operation – The content item's name was changed.
content_item_variant
typearchive
operation – The content item's variant was deleted.change_workflow_step
operation – The content item's variant was moved to a different workflow step.restore
operation – The content item's variant was restored in a specific language after deletion.publish
operation – The content item's variant was published.unpublish
operation – The content item's variant was unpublished.
content_type
typeupsert
operation – The content type used for existing content items was changed.
language_settings
typeupsert
operation – The language's codename was changed.
project
typearchive
operation – The project was archived.restore
operation – The project was restored.
taxonomy
typearchive
operation – A taxonomy group was deleted.restore
operation – A taxonomy group was restored after deletion.upsert
operation – A taxonomy group was changed.
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 the notifications.
Kontent may send webhook notifications from the following IP addresses.
- 13.69.68.1
- 40.115.59.104
- 104.47.142.248
- 104.47.143.150
- 104.47.144.212
- 104.47.161.32
- 104.47.161.68
- 104.47.161.137
The list is subject to change.