Webhooks

Is this page helpful?
  • javascript icon
    JavaScript
  • typescript icon
    TypeScript
  • dot-net icon
    .NET
  • java icon
    Java
  • php icon
    PHP
  • ruby icon
    Ruby
  • curl icon
    REST
calendar icon
user iconJan Cerman
clock icon27 minutes
bullseye iconWebhooks
arrow-down-line iconDownload PDF
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.

Create webhooks

You can create webhooks via API or UI.
  1. In Kontent.ai, go to cogwheel icon Environment settings > Webhooks.
  2. Click Create new webhook.
  3. In General> Webhook name, type a name for the webhook, such as Cache invalidate.
  4. In General > Webhook URL, type a publicly available URL address of your app’s endpoint, such as https://example.com/refresh-content.
  5. (Optional) In Settings > Headers, specify custom headers as key-value pairs to send along with the webhook notification.
  6. In Triggers > Published or preview, select whether the webhook is triggered by changes in Published data or Preview data.
  7. 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.
  8. 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.

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 base64arrow-right-top-square icon-encoded hash generated using an HMAC-SHA-256arrow-right-top-square icon 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.

Get the latest content

After you verify a received notification, you might want to request the latest content. By default, Delivery API serves stale contentarrow-right-top-square icon (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.

Webhook payload structure

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.
  • id (string): The object’s internal ID.
  • name (string): The object’s display name.
  • codename (string): The object’s codename.
  • 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-8601arrow-right-top-square icon 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.
  • 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 headersarrow-right-top-square icon 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.
  • hostarrow-right-top-square icon (string): The URL to which the webhook notification was sent.
  • content-lengtharrow-right-top-square icon (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.
  • traceparentarrow-right-top-square icon (string): The internal trace information of the webhook notification.
  • content-typearrow-right-top-square icon (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:
  • Each webhook can specify up to 10 custom headers.
  • The header key must be different from the reserved headers.
  • 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.
EventOccurs whenobject_typeaction
Asset createdCreating an assetassetcreated
Asset updatedReplacing the asset’s binary fileassetchanged
Asset deletedDeleting an unused assetassetdeleted
Asset metadata changed
  • Changing asset codename
  • Changing asset description
  • Changing asset title
  • Moving an asset to another collection
assetmetadata_changed
Example: JSON payload for an asset item event when an asset's metadata is changed.

Content item events

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.

Content item events for published data

EventOccurs whenobject_typeaction
Content item metadata changed
  • Changing a content item codename
  • Changing a content item name
  • Moving a content item to another collection
content_itemmetadata_changed
Content item variant publishedPublishing a content item variantcontent_itempublished
Content item variant unpublishedUnpublishing a content item variantcontent_itemunpublished
Example: JSON payload for a publish content item event when an item is unpublished.

 Content item events for preview data

EventOccurs whenobject_typeaction
Content item metadata changed
  • Changing a content item codename
  • Changing a content item name
  • Moving a content item to another collection
content_itemmetadata_changed
Content item variant createdCreating a content itemcontent_itemcreated
Content item variant updatedChanging a content item variant's contentcontent_itemchanged
Content item variant deletedDeleting a content item variantcontent_itemdeleted
Workflow step changed toMoving a content item to a specific workflow stepcontent_itemworkflow_step_changed
Example: JSON payload for a preview content item event when an item is unpublished.

Content type events

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.
EventOccurs whenobject_typeaction
Content type createdCreating a content typecontent_typecreated
Content type updated
  • Renaming a content type
  • Changing a content type codename
  • Changing element configuration
  • Changing a snippet used in the content type
content_typechanged
Content type deletedDeleting an unused content typecontent_typedeleted
Example: JSON payload for a content type event when a type is changed.

Language events

Language events inform you about the changes made in the localization settings. You can filter the language events to changes made in specific languages.
EventOccurs whenobject_typeaction
Language createdCreating or activating a languagelanguagecreated
Language updated
  • Renaming a language
  • Changing a language codename
  • Changing a language fallback
languagechanged
Language deletedDeactivating a languagelanguagedeleted
Example: JSON payload for a language event when a language is deactivated.

Taxonomy events

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.
EventOccurs whenobject_typeaction
Taxonomy group createdCreating a taxonomy grouptaxonomycreated
Taxonomy group metadata changed
  • Changing a taxonomy group codename
  • Renaming a taxonomy group
taxonomymetadata_changed
Taxonomy group deletedDeleting a taxonomy grouptaxonomydeleted
Taxonomy term createdCreating a taxonomy termtaxonomyterm_created
Taxonomy term changed
  • Changing a taxonomy term codename
  • Renaming a taxonomy term
taxonomyterm_changed
Taxonomy term deletedDeleting a taxonomy termtaxonomyterm_deleted
Taxonomy terms movedReordering taxonomy terms in a taxonomy group taxonomyterms_moved
Example: JSON payload for a taxonomy event when a taxonomy term is created.

Retry policy

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 settings permission 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 cogwheel icon Environment settings > Webhooks, you can find a list of your webhooks and their health statuses.
  • i-circle icon Ready for message – appears for newly created webhooks before any change to published content has been made (so no notification has been sent).
  • cb-check icon Working – appears for webhooks that have properly delivered notifications.
  • exclamation-triangle-inverted icon 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.
  • exclamation-triangle icon 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 bug icon. 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 xml-tag icon to view the most recent response.
    • In the window that pops up, use the button doc-copy icon 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.
  1. In Kontent.ai, go to cogwheel icon Environment settings > Webhooks.
  2. For a failing or dead webhook, click rotate-left icon 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.
  1. In Kontent.ai, go to cogwheel icon Environment settings > Webhooks.
  2. Click a webhook to open its details.
  3. Click drawers icon 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:
  • 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
  • Docs
  • AI accelerators
  • Collections
  • Custom elements
  • Environments
  • Keyboard shortcuts
  • Mission Control
  • Projects
  • Spaces
  • Task management
  • Terminology
No code sample for this language yet. Try selecting another language at the top.
  • JSON
  • JSON
  • JSON
  • JSON
  • JSON
  • JSON
  • JSON
  • desktop-alt icon
  • Cheat sheets
  • Documentation
  • API reference
  • Product updates
Kontent.ai Learn
  • Plan
  • Set up
  • Model
  • Develop
  • Create
  • Webhooks
  • Legacy webhooks
  • Migrate from legacy webhooks
Copyright © 2024 Kontent.aiarrow-right-top-square icon. All rights reserved.
  • Webarrow-right-top-square icon
  • Privacy policyarrow-right-top-square icon
  • Cookies policy
  • Consent settingsarrow-right-top-square icon
  • Securityarrow-right-top-square icon
  • GDPRarrow-right-top-square icon
{
  "notifications": [
    {
      "data": {
        "system": {
          "id": "32022d85-ee58-4655-9016-e130c375820a",
          "name": "This changes everything!",
          "codename": "this_changes_everything",
          "collection": "marketing",
          "workflow": "default",
          "workflow_step": "published",
          "language": "english",
          "type": "product_update",
          "last_modified": "2024-01-08T13:54:54.3153716Z"
        }
      },
      "message": {
        "environment_id": "5f313984-9216-0158-9068-1d194f578bce",
        "object_type": "content_item",
        "action": "published",
        "delivery_slot": "published"
      }
    }
  ]
}
{
    "notifications": [
      {
        "data": {
          "system": {
            "id": "f24e4721-f081-50ef-9a47-2ebd45b0c915",
            "name": "sofia-patel.jpg",
            "codename": "sofia_patel_jpg",
            "last_modified": "2024-02-15T13:10:36.8256346Z",
            "collection": "default"
          }
        },
        "message": {
          "environment_id": "195a50c1-f1b8-0066-9eb4-83f7246d5459",
          "object_type": "asset",
          "action": "metadata_changed",
          "delivery_slot": "preview"
        }
      }
    ]
  }
{
  "notifications": [
    {
      "data": {
        "system": {
          "id": "ad2db98c-f4fe-5ce7-bd99-488b6b61d280",
          "name": "Solutions",
          "codename": "solutions_imaging",
          "collection": "ficto_imaging",
          "workflow": "default",
          "workflow_step": "published",
          "language": "default",
          "type": "navigation_item",
          "last_modified": "2023-09-12T15:24:05.8881433Z"
        }
      },
      "message": {
        "environment_id": "195a50c1-f1b8-0066-9eb4-83f7246d5459",
        "object_type": "content_item",
        "action": "unpublished",
        "delivery_slot": "published"
      }
    }
  ]
}
{
  "notifications": [
    {
      "data": {
        "system": {
          "id": "ad2db98c-f4fe-5ce7-bd99-488b6b61d280",
          "name": "Solutions",
          "codename": "solutions_imaging",
          "collection": "ficto_imaging",
          "workflow": "default",
          "workflow_step": "archived",
          "language": "default",
          "type": "navigation_item",
          "last_modified": "2023-09-12T15:24:05.8881433Z"
        }
      },
      "message": {
        "environment_id": "195a50c1-f1b8-0066-9eb4-83f7246d5459",
        "object_type": "content_item",
        "action": "workflow_step_changed",
        "delivery_slot": "preview"
      }
    }
  ]
}
{
    "notifications": [
      {
        "data": {
          "system": {
            "id": "121d16aa-de4b-454f-9174-e26f25f1d860",
            "name": "💡 Page",
            "codename": "page",
            "last_modified": "2024-02-15T13:17:12.6761225Z"
          }
        },
        "message": {
          "environment_id": "195a50c1-f1b8-0066-9eb4-83f7246d5459",
          "object_type": "content_type",
          "action": "changed",
          "delivery_slot": "preview"
        }
      }
    ]
  }
{
  "notifications": [
    {
      "data": {
        "system": {
          "id": "b25ecaa3-a356-4d8e-9d86-46ce295cbf22",
          "name": "Spanish",
          "codename": "es-ES",
          "last_modified": "2024-02-15T13:21:42.1300774Z"
        }
      },
      "message": {
        "environment_id": "195a50c1-f1b8-0066-9eb4-83f7246d5459",
        "object_type": "language",
        "action": "deleted",
        "delivery_slot": "published"
      }
    }
  ]
}
{
    "notifications": [
      {
        "data": {
          "system": {
            "id": "0308d684-96c6-4896-8784-c8590608c672",
            "name": "Handheld",
            "codename": "handheld",
            "last_modified": "2024-02-15T13:23:29.3147543Z",
            "taxonomy_group": "product_category"
          }
        },
        "message": {
          "environment_id": "195a50c1-f1b8-0066-9eb4-83f7246d5459",
          "object_type": "taxonomy",
          "action": "term_created",
          "delivery_slot": "published"
        }
      }
    ]
  }
scheme-path-circles-flipped icon
i-circle icon
  • Ruby
exclamation-triangle icon
  • Sign in
    • # Tip: Find more about Ruby SDKs at https://kontent.ai/learn/ruby
require 'delivery-sdk-ruby'

delivery_client = Kontent::Ai::Delivery::DeliveryClient.new project_id: '<YOUR_ENVIRONMENT_ID>'
delivery_client.item('my_article')
               .request_latest_content
               .execute do |response|
                 item = response.item
               end
    Explore your path to mastery
    • Discover how to automate processes and content updates with webhooks.
    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.
    The list is subject to change.
  • Create webhooks
  • Validate received notifications
  • Get the latest content
  • Webhook payload structure
  • Webhook headers
  • Webhook triggers and events
  • Retry policy
  • Email notifications
  • Debug webhooks
  • Outbound IP addresses