Webhooks provide an event-based notification mechanism. They immediately let you know about specific changes as they happen. You can integrate Kontent.ai with other apps and automate your processes with webhooks.
The new webhooks experience
We’re rebuilding our webhooks from the ground up to provide you with a better experience. The new webhooks are currently available via an early access program. If you’d like to try the new webhooks, let us know your environment ID in chat.
The new webhooks live alongside your current webhooks. Your existing webhooks stay as they are.You can use the new webhooks to get notified about changes in your assets and content types.
In Kontent.ai, go to Environment settings > New webhooks.
Click Create new webhook.
In Webhook name, type a name for the webhook, such as Cache invalidate.
In URL address, type a publicly available URL address of your app’s endpoint, such as https://example.com/cache-invalidate.
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.
Validate received notifications
Kontent.ai sends webhook notifications as POST requests. 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.Each notification contains the X-Kontent-ai-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-Kontent-ai-Signature header value.
New webhook triggers and events
Preview data vs. published data
When deciding what events will trigger your webhooks, you need to choose whether you’re interested in events for the published data or preview data.For assets and content types, this selection makes no difference. Assets and content types are the same in published and preview data.
Asset deleted event (object_type: asset and action: deleted) occurs when someone deletes an unused asset. This means the asset wasn’t used in any content item or guidelines.
Content type events
Content type events inform you about the changes related to your content types.
Content type created or updated event (object_type: content_type and action: changed) occurs when:
A new content type is created.
An existing content type is modified. For example, this can occur when the content type’s name or codename changes, the element configuration changes, or a snippet used in the content type changes.
Content type deleted event (object_type: content_type and action: deleted) occurs when someone deletes an unused content type. This means the type wasn’t used for any content item or component.
New webhook payload structure
Kontent.ai sends the new webhook notifications as POST requests to your webhook URL. These requests contain a JSON payload that tells you which objects changed and due to which event.For example, here’s a JSON payload sent for the Content type created or updated event. The payload has two parts:
data object – tells you what data in your environment was affected. That is metadata information of the affected object, such as asset or content type.
Stay tuned for more!In the upcoming months, you’ll be able to use the new webhooks to:
Extend the webhook notifications with custom headers to, for example, authorize the notifications against your web app.
Know when content items based on specific types and languages change using content item events with advanced filtering.
Know when language configuration changes based on specific language events.
Know when taxonomies change based on specific taxonomy events.
The choice between preview data and published data is important for content items. Support for content items is coming soon.
Published data includes published versions of content items.
Preview data includes the latest versions of content items, which can be published or draft versions.
One notification for one object changeThe notification array in the JSON payload contains a single object. This will change soon.We’re working on batching notifications related to a single event into a single JSON payload. For example, this is useful when one event, such as a taxonomy update, affects a lot of assets or content items.