Legacy webhooks | Kontent.ai Learn

Create legacy webhooks

Legacy webhooks are available only in subscriptions created before December 14, 2023.

In Kontent.ai, go to Environment settings > Legacy 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, select which events will trigger the webhook.
Click Save.

You can also create and manage legacy webhooks via API.

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

Get the latest content

After you get a notification about changed content, you might want to explicitly request the latest content from the API. By default, Delivery API serves stale content

(provided it’s cached by the CDN) while fetching the latest content to minimize wait time. To request the latest content from your project, send a request to Delivery API with the 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.

Legacy webhook triggers and events

When you create webhooks, you specify the events that trigger the webhook. 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 are triggered when a content item is moved to a specific workflow step.
Content item events are 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 are triggered when a content item is published or unpublished based on your selection.
Taxonomy events are triggered when a taxonomy group is created (or updated), deleted, or restored after being deleted based on your selection.

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 are triggered when a content item is created, updated, or deleted based on your selection.
Taxonomy events are triggered when a taxonomy group is created or updated, deleted, or restored after being deleted, based on your selection.

Legacy webhook payload structure

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 notification’s origin. For example, here’s a webhook notification sent as a result of the content item Publish event.

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.

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.

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.

Message object

The webhook’s 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 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.

Types and operations

The values of the 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 – A content item name was changed.
content_item_variant type
- archive operation – A content item variant was deleted.
- change_workflow_step operation – A content item variant was moved to a different workflow step.
- restore operation – A content item variant was restored in a specific language after deletion.
- publish operation – A content item variant was published.
- upsert operation – A content item variant was updated.
- unpublish operation – A content item 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 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 codename or workflow step codename was changed.

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.

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 is repeatedly failing for 1 hour. This email is sent only once for each registered webhook.
Notification delivery is 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

Environment settings > Legacy 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.

Find information about your webhooks

For more information about each webhook, click

. 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 to view the most recent response.
- In the window that pops up, use the button 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.

In Kontent.ai, go to Environment settings > Legacy webhooks.
Select a failing or dead webhook to open its details.
Click 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.

In Kontent.ai, go to Environment settings > Legacy webhooks.
Click a webhook to open its details.
Click 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

{
  "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"
}

<?php
// Example of generating the hash to verify the notification
$givenSignature = $_SERVER['HTTP_X_KC_SIGNATURE'];
$computedSignature = base64_encode(hash_hmac('sha256', $json_message, $secret, true));

$result = hash_equals($givenSignature, $computedSignature);
?>

<?php
// Tip: Find more about PHP SDKs at https://kontent.ai/learn/php
// Defined by Composer to include required libraries
require __DIR__ . '/vendor/autoload.php';

use Kontent\Ai\Delivery\DeliveryClient;

$client = new DeliveryClient("<YOUR_ENVIRONMENT_ID>", null, true);

$item = $client->getItem('my_article');
?>