Skip navigation

Webhooks reference

Jan Cerman
10 min read
Download PDF

Webhooks provide an event-based notification mechanism. They immediately let you know about specific changes as they happen.

Table of contents

    Events to trigger a webhook

    When you create a webhook, you specify the events that trigger the webhook. These events are usually the results of specific user actions in the UI but they can be triggered by changes made via Management API as well.

    The events are divided based on the type and purpose of the notifications. For example, if you need to rebuild your static site to preview the latest changes, you 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 use the events under Management API triggers.

    Choose events based on your use case after receiving the notification. Your content is synchronized across Management API, Delivery API, and Delivery Preview API.

    Management API triggers

    Management API triggers let you subscribe to specific changes to your content in 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.

    Delivery API triggers

    Delivery API triggers let you subscribe to specific changes to your published content in Delivery API.

    • 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.

    Content publishing as two events

    When you publish a content item, its workflow step first changes to the Published step. Then the item becomes available via Delivery API.

    These are two separate events. The first event is the transition to the Published workflow step under Management API triggers. The second event is the Publish event for content items under Delivery API triggers. You can subscribe to both events if needed.

    Delivery Preview API triggers

    Delivery Preview API triggers let you subscribe to specific changes to your latest content in Delivery Preview API, which contains both 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.ai sends notifications as POST requests to your webhook URL. Every 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.

    • JSON
    {
  "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": "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 object

    The Data object contains metadata of the changed content. For example, if you change a taxonomy group that's used in multiple published content items, you get a notification with information about the changed taxonomy group together with the affected content items.

    • JSON
    {
  "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": { ... }
}
    {
  "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": { ... }
}

    Item objects

    Due to the variety of events you can subscribe to, the 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.

    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.
    • collection (string): The collection'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 find which environment the notification came from and what operation caused it.

    • 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's 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.
    • JSON
    "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 Message object's 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 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
    • 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.

    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.ai might 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.

    What's next?