Webhooks
Is this page helpful?
Environment settings > Webhooks, or Environment settings > Legacy webhooks if you have new webhooks enabled.
https://example.com/cache-invalidate.X-KC-Signature HTTP header with a checksum of the JSON payload. You can use the header’s value to verify the authenticity of the notification. This way, you can check that the notification came from Kontent.ai, not someone else.
The signature is a base64 encoded hash generated using an HMAC-SHA-256 with the webhook’s secret key.
To verify the received notification, use the JSON payload (the raw body of the notification as-is) and the generated webhook Secret as the secret for the HMAC function. The secret is unique for each webhook. Once you generate a hash, compare the hash value with the X-KC-Signature header value.
X-KC-Wait-For-Loading-New-Content header set to true. The header determines whether to wait while fetching content if the requested content has changed since the last request.
items array in the Data object might contain different types of Item objects. The type of the Item objects is never mixed within a single notification.
id (string): The content item’s internal ID.codename (string): The content item’s codename.collection (string): The collection’s codename.language (string): The language’s codename.type (string): The content type’s codename.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.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.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.ai API that the notification relates to. Possible values are delivery_production for the Delivery API, delivery_preview for the Delivery Preview API, and content_management for the Management API.project_id (string): The environment ID, formerly named project ID.webhook_url (string): A publicly available URL address of your webhook endpoint, for example, https://example.com/cache-invalidate.created_timestamp (string): ISO-8601 formatted UTC time and date, for example, YYYY-MM-DDTHH:MM:SSZ.type and operation properties in the webhook's Message object tell you what changed and how. The type property answers the what, and the operation property answers the how.
The list below contains common 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 type
upsert operation – For one or more assets used in content items, the asset description (alt text) was changed, or the asset was replaced.content_item type
upsert operation – The content item’s name was changed.content_item_variant type
archive 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 type
upsert operation – A content type used with existing content items was changed.language_settings type
upsert operation – A language’s codename was changed.project type
archive operation – The project was archived.restore operation – The project was restored.project_settings type
upsert operation – The language fallback behavior used when retrieving localized content was changed.taxonomy type
archive operation – A taxonomy group was deleted.restore operation – A taxonomy group was restored after deletion. upsert operation – A taxonomy group was changed.workflow type
upsert operation – A workflow step’s codename was changed. 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.
. 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:
to view the most recent response.
to copy the response to the clipboard. Environment settings > Webhooks. Environment settings > Webhooks.
Disable.{
"data": {
"items": [
{
"id": "e5d575fe-9608-4523-a07d-e32d780bf92a",
"codename": "published_article",
"collection": "default",
"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": "e113e464-bffb-4fbd-a29b-47991d003732",
"codename": "report_for_2019",
"collection": "default",
"language": "en-US",
"type": "article"
},
{
"id": "e113e464-bffb-4fbd-a29b-47991d003732",
"codename": "report_for_2020",
"collection": "default",
"language": "en-US",
"type": "article"
}
],
"taxonomies": [
{
"id": "4794dde6-f700-4a5d-b0dc-9ae16dcfc73d",
"codename": "category"
}
]
},
"message": { ... }
}"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"
}items arrayWhen 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.taxonomies array is not present for notifications about workflow step transitions.X-KC-Message. For example, the Message object’s project_id property is mirrored by the X-KC-Message-Project-Id header.// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
const signatureHelper = require('@kontent-ai/webhook-helper');
// Example of generating the hash to verify the notification
const isValidSignature = (req, secret) => {
return signatureHelper.isValidSignatureFromString(
req.body, // Use raw body data from the request, i.e., by using body-parser
secret,
req.headers['x-kc-signature']
);
};// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
const KontentDelivery = require('@kontent-ai/delivery-sdk');
const deliveryClient = KontentDelivery.createDeliveryClient({
environmentId: '<YOUR_ENVIRONMENT_ID>',
});
const response = await deliveryClient.item('my_article')
.queryConfig({ waitForLoadingNewContent: true })
.toPromise();