• Cheat sheets
  • Documentation
  • API reference
  • Product updates
  • Sign in
Kontent.ai Learn
  • Try Kontent.ai
  • Plan
  • Set up
  • Model
  • Develop
  • Create
Management API v2
API Reference
    • About Management API
    • Postman collection
    • SDKs
    • Authentication
    • API keys
    • API limitations
    • Guidelines on handling changes
      • Introduction
      • Webhook object
        Schema
      • Add a webhook
        POST
      • Retrieve webhooks
        GET
      • Retrieve a webhook
        GET
      • Enable a webhook
        PUT
      • Disable a webhook
        PUT
      • Delete a webhook
        DELETE

Webhooks

Use webhooks to receive real-time notifications about changes in your environments. You can get notified about changes in your assets, content items, content types, languages, and taxonomy groups. Learn more about how to set up webhooks.
If you get a notification about archived assets or content items, you can check if the assets or items are in use through Delivery API:
  • List items that reference an asset
  • List items that reference an item
This gives you the information required to keep your cache up to date and identify content dependencies.

Webhook object

The webhook object specifies the configuration for a webhook in your environment. This includes the webhook URL, a secret key for validating notification authenticity, and details about the events that trigger the webhook.
id
string · read-only · uuid
The webhook's internal ID.
name
required · string · 1-200 chars
The webhook's display name.
url
required · string · 1-250 chars · url
The webhook's URL. Kontent.ai will send notifications to this URL.
secret
required · string
The webhook's secret key. Use the secret key to validate notification authenticity.When creating webhooks via API, you need to provide your own secret value. We recommend using a CSPRNG for this. In the UI, the secret is automatically generated for you.
headers[]
array · max. 10 items
The webhook's custom HTTP headers. This is useful if you need to send extra information, such as authentication details, along with the webhook notification body.If you specify multiple headers with the same key for the webhook, the header values will be added to a comma-separated list and sent as a single HTTP header, such as "custom_key": "value1, value2, value3".
enabled
boolean
Determines if the webhook is enabled. By default, the enabled property is set to true.
  • Enabled webhooks react to the defined triggers, create notifications, and try to send the notifications to the specified webhook URL in the order of creation.
  • Disabled webhooks ignore the defined triggers and do not create any notifications.
last_modified
string · read-only · date-time
ISO-8601 formatted date & time of the last change to the webhook. 
health_status
string · read-only
The webhook's health status tells you whether the webhook is operational. Use this information to debug your webhooks.
Accepted values:
unknown, working, failing, dead
delivery_triggers
required · object
Specifies which events will trigger the webhook. The events can be set for the published or preview data in Delivery API.
JSON
{
  "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
  "name": "Example webhook",
  "url": "https://example.com/webhook",
  "secret": "fNp+QH1sE+fSXoNFlQ4kwiTJz0er2L34gFItAAVHws8=",
  "headers": [
    {
      "key": "api-key",
      "value": "Secret API key value"
    },
    {
      "key": "Custom-key",
      "value": "Custom header value with alphanum3r1c characters."
    }
  ],
  "enabled": true,
  "last_modified": "2023-09-18T09:29:08.4356117Z",
  "health_status": "working",
  "delivery_triggers": {
    "slot": "preview",
    "events": "specific",
    "content_type": {
      "enabled": true,
      "actions": [
        {
          "action": "changed"
        }
      ],
      "filters": {
        "content_types": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ]
      }
    },
    "content_item": {
      "enabled": true,
      "actions": [
        {
          "action": "workflow_step_changed",
          "transition_to": [
            {
              "workflow_identifier": {
                "id": "131a952b-ead3-448f-84f4-644d5fea49b1"
              },
              "step_identifier": {
                "id": "b4363ccd-8f21-45fd-a840-5843d7b7f008"
              }
            },
            {
              "workflow_identifier": {
                "id": "ee4aa121-fcdf-417e-bcc2-929a94a83727"
              },
              "step_identifier": {
                "id": "88ac5e6e-1c5c-4638-96e1-0d61221ad5bf"
              }
            }
          ]
        }
      ],
      "filters": {
        "collections": [
          {
            "id": "a1b6c97b-0af1-4791-bdc8-b5d0556004ae"
          }
        ],
        "content_types": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ],
        "languages": [
          {
            "id": "16ec3fdb-cb3d-42ea-a179-6fd682d4a25b"
          }
        ]
      }
    },
    "taxonomy": {
      "enabled": true,
      "actions": [
        {
          "action": "term_changed"
        }
      ],
      "filters": {
        "taxonomies": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ]
      }
    },
    "asset": {
      "enabled": true,
      "actions": [
        {
          "action": "deleted"
        }
      ]
    },
    "language": {
      "enabled": true,
      "actions": [
        {
          "action": "changed"
        },
        {
          "action": "created"
        }
      ],
      "filters": {
        "languages": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ]
      }
    }
  }
}

Add a webhook

Add a webhook to a given environment.
POST
https://manage.kontent.ai/v2/projects/{environment_id}/webhooks-vnext

Request

Path parameters

environment_id
required · string
Identifies your environment.

Body schema

Application/json

The webhook to be added.

name
required · string · 1-200 chars
The webhook's display name.
url
required · string · 1-250 chars · url
The webhook's URL. Kontent.ai will send notifications to this URL.
secret
required · string
The webhook's secret key. Use the secret key to validate notification authenticity.When creating webhooks via API, you need to provide your own secret value. We recommend using a CSPRNG for this. In the UI, the secret is automatically generated for you.
headers[]
array · max. 10 items
The webhook's custom HTTP headers. This is useful if you need to send extra information, such as authentication details, along with the webhook notification body.If you specify multiple headers with the same key for the webhook, the header values will be added to a comma-separated list and sent as a single HTTP header, such as "custom_key": "value1, value2, value3".
enabled
boolean
Determines if the webhook is enabled. By default, the enabled property is set to true.
  • Enabled webhooks react to the defined triggers, create notifications, and try to send the notifications to the specified webhook URL in the order of creation.
  • Disabled webhooks ignore the defined triggers and do not create any notifications.
delivery_triggers
required · object
Specifies which events will trigger the webhook. The events can be set for the published or preview data in Delivery API.

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .addWebhook()
  .withData({
    name: 'Example webhook',
    url: 'https://example.com/webhook',
    secret: 'secret_key',
    delivery_triggers: {
      slot: 'preview',
      events: 'specific',
      content_type: {
        enabled: 'true',
        actions: [
          {
            action: 'changed',
          },
        ],
      },
      asset: {
        enabled: 'true',
        actions: [
          {
            action: 'deleted',
          },
        ],
      },
      taxonomy: {
        enabled: 'true',
        actions: [
          {
            action: 'term_changed',
          },
        ],
      },
      language: {
        enabled: 'true',
        actions: [
          {
            action: 'changed',
          },
          {
            action: 'created',
          },
        ],
      },
      content_item: {
        enabled: 'true',
        actions: [
          {
            action: 'workflow_step_changed',
            transition_to: [],
          },
        ],
        filters: {
          collections: [{}],
          content_types: [{}],
          languages: [{}],
        },
      },
    },
  })
  .toPromise();

Response

Status (201)
The added webhook object.
id
string · read-only · uuid
The webhook's internal ID.
name
required · string · 1-200 chars
The webhook's display name.
url
required · string · 1-250 chars · url
The webhook's URL. Kontent.ai will send notifications to this URL.
secret
required · string
The webhook's secret key. Use the secret key to validate notification authenticity.When creating webhooks via API, you need to provide your own secret value. We recommend using a CSPRNG for this. In the UI, the secret is automatically generated for you.
headers[]
array · max. 10 items
The webhook's custom HTTP headers. This is useful if you need to send extra information, such as authentication details, along with the webhook notification body.If you specify multiple headers with the same key for the webhook, the header values will be added to a comma-separated list and sent as a single HTTP header, such as "custom_key": "value1, value2, value3".
enabled
boolean
Determines if the webhook is enabled. By default, the enabled property is set to true.
  • Enabled webhooks react to the defined triggers, create notifications, and try to send the notifications to the specified webhook URL in the order of creation.
  • Disabled webhooks ignore the defined triggers and do not create any notifications.
last_modified
string · read-only · date-time
ISO-8601 formatted date & time of the last change to the webhook. 
health_status
string · read-only
The webhook's health status tells you whether the webhook is operational. Use this information to debug your webhooks.
Accepted values:
unknown, working, failing, dead
delivery_triggers
required · object
Specifies which events will trigger the webhook. The events can be set for the published or preview data in Delivery API.

Example responses

201
400
{
  "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
  "name": "Example webhook",
  "url": "https://example.com/webhook",
  "secret": "fNp+QH1sE+fSXoNFlQ4kwiTJz0er2L34gFItAAVHws8=",
  "headers": [
    {
      "key": "api-key",
      "value": "Secret API key value"
    },
    {
      "key": "Custom-key",
      "value": "Custom header value with alphanum3r1c characters."
    }
  ],
  "enabled": true,
  "last_modified": "2023-09-18T09:29:08.4356117Z",
  "health_status": "working",
  "delivery_triggers": {
    "slot": "preview",
    "events": "specific",
    "content_type": {
      "enabled": true,
      "actions": [
        {
          "action": "changed"
        }
      ],
      "filters": {
        "content_types": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ]
      }
    },
    "content_item": {
      "enabled": true,
      "actions": [
        {
          "action": "workflow_step_changed",
          "transition_to": [
            {
              "workflow_identifier": {
                "id": "131a952b-ead3-448f-84f4-644d5fea49b1"
              },
              "step_identifier": {
                "id": "b4363ccd-8f21-45fd-a840-5843d7b7f008"
              }
            },
            {
              "workflow_identifier": {
                "id": "ee4aa121-fcdf-417e-bcc2-929a94a83727"
              },
              "step_identifier": {
                "id": "88ac5e6e-1c5c-4638-96e1-0d61221ad5bf"
              }
            }
          ]
        }
      ],
      "filters": {
        "collections": [
          {
            "id": "a1b6c97b-0af1-4791-bdc8-b5d0556004ae"
          }
        ],
        "content_types": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ],
        "languages": [
          {
            "id": "16ec3fdb-cb3d-42ea-a179-6fd682d4a25b"
          }
        ]
      }
    },
    "taxonomy": {
      "enabled": true,
      "actions": [
        {
          "action": "term_changed"
        }
      ],
      "filters": {
        "taxonomies": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ]
      }
    },
    "asset": {
      "enabled": true,
      "actions": [
        {
          "action": "deleted"
        }
      ]
    },
    "language": {
      "enabled": true,
      "actions": [
        {
          "action": "changed"
        },
        {
          "action": "created"
        }
      ],
      "filters": {
        "languages": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ]
      }
    }
  }
}

Retrieve webhooks

Retrieves webhooks from an environment.
GET
https://manage.kontent.ai/v2/projects/{environment_id}/webhooks-vnext

Request

Path parameters

environment_id
required · string
Identifies your environment.

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client.listWebhooks().toPromise();

Response

Status (200)
A list of webhooks.
array

Example responses

200
{
  "": [
    {
      "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
      "name": "Example webhook",
      "url": "https://example.com/webhook",
      "secret": "fNp+QH1sE+fSXoNFlQ4kwiTJz0er2L34gFItAAVHws8=",
      "headers": [
        {
          "key": "api-key",
          "value": "Secret API key value"
        },
        {
          "key": "Custom-key",
          "value": "Custom header value with alphanum3r1c characters."
        }
      ],
      "enabled": true,
      "last_modified": "2023-09-18T09:29:08.4356117Z",
      "health_status": "working",
      "delivery_triggers": {
        "slot": "preview",
        "events": "specific",
        "content_type": {
          "enabled": true,
          "actions": [
            {
              "action": "changed"
            }
          ],
          "filters": {
            "content_types": [
              {
                "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
              }
            ]
          }
        },
        "content_item": {
          "enabled": true,
          "actions": [
            {
              "action": "workflow_step_changed",
              "transition_to": [
                {
                  "workflow_identifier": {
                    "id": "131a952b-ead3-448f-84f4-644d5fea49b1"
                  },
                  "step_identifier": {
                    "id": "b4363ccd-8f21-45fd-a840-5843d7b7f008"
                  }
                },
                {
                  "workflow_identifier": {
                    "id": "ee4aa121-fcdf-417e-bcc2-929a94a83727"
                  },
                  "step_identifier": {
                    "id": "88ac5e6e-1c5c-4638-96e1-0d61221ad5bf"
                  }
                }
              ]
            }
          ],
          "filters": {
            "collections": [
              {
                "id": "a1b6c97b-0af1-4791-bdc8-b5d0556004ae"
              }
            ],
            "content_types": [
              {
                "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
              }
            ],
            "languages": [
              {
                "id": "16ec3fdb-cb3d-42ea-a179-6fd682d4a25b"
              }
            ]
          }
        },
        "taxonomy": {
          "enabled": true,
          "actions": [
            {
              "action": "term_changed"
            }
          ],
          "filters": {
            "taxonomies": [
              {
                "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
              }
            ]
          }
        },
        "asset": {
          "enabled": true,
          "actions": [
            {
              "action": "deleted"
            }
          ]
        },
        "language": {
          "enabled": true,
          "actions": [
            {
              "action": "changed"
            },
            {
              "action": "created"
            }
          ],
          "filters": {
            "languages": [
              {
                "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
              }
            ]
          }
        }
      }
    }
  ]
}

Retrieve a webhook

Retrieves a webhook specified by its internal ID.
GET
https://manage.kontent.ai/v2/projects/{environment_id}/webhooks-vnext/{webhook_identifier}

Request

Path parameters

environment_id
required · string
Identifies your environment.
webhook_identifier
required · string
Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .getWebhook()
  .byId('5df74e27-1213-484e-b9ae-bcbe90bd5990')
  .toPromise();

Response

Status (200)
A single webhook object.
id
string · read-only · uuid
The webhook's internal ID.
name
required · string · 1-200 chars
The webhook's display name.
url
required · string · 1-250 chars · url
The webhook's URL. Kontent.ai will send notifications to this URL.
secret
required · string
The webhook's secret key. Use the secret key to validate notification authenticity.When creating webhooks via API, you need to provide your own secret value. We recommend using a CSPRNG for this. In the UI, the secret is automatically generated for you.
headers[]
array · max. 10 items
The webhook's custom HTTP headers. This is useful if you need to send extra information, such as authentication details, along with the webhook notification body.If you specify multiple headers with the same key for the webhook, the header values will be added to a comma-separated list and sent as a single HTTP header, such as "custom_key": "value1, value2, value3".
enabled
boolean
Determines if the webhook is enabled. By default, the enabled property is set to true.
  • Enabled webhooks react to the defined triggers, create notifications, and try to send the notifications to the specified webhook URL in the order of creation.
  • Disabled webhooks ignore the defined triggers and do not create any notifications.
last_modified
string · read-only · date-time
ISO-8601 formatted date & time of the last change to the webhook. 
health_status
string · read-only
The webhook's health status tells you whether the webhook is operational. Use this information to debug your webhooks.
Accepted values:
unknown, working, failing, dead
delivery_triggers
required · object
Specifies which events will trigger the webhook. The events can be set for the published or preview data in Delivery API.

Example responses

200
404
{
  "id": "5df74e27-1213-484e-b9ae-bcbe90bd5990",
  "name": "Example webhook",
  "url": "https://example.com/webhook",
  "secret": "fNp+QH1sE+fSXoNFlQ4kwiTJz0er2L34gFItAAVHws8=",
  "headers": [
    {
      "key": "api-key",
      "value": "Secret API key value"
    },
    {
      "key": "Custom-key",
      "value": "Custom header value with alphanum3r1c characters."
    }
  ],
  "enabled": true,
  "last_modified": "2023-09-18T09:29:08.4356117Z",
  "health_status": "working",
  "delivery_triggers": {
    "slot": "preview",
    "events": "specific",
    "content_type": {
      "enabled": true,
      "actions": [
        {
          "action": "changed"
        }
      ],
      "filters": {
        "content_types": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ]
      }
    },
    "content_item": {
      "enabled": true,
      "actions": [
        {
          "action": "workflow_step_changed",
          "transition_to": [
            {
              "workflow_identifier": {
                "id": "131a952b-ead3-448f-84f4-644d5fea49b1"
              },
              "step_identifier": {
                "id": "b4363ccd-8f21-45fd-a840-5843d7b7f008"
              }
            },
            {
              "workflow_identifier": {
                "id": "ee4aa121-fcdf-417e-bcc2-929a94a83727"
              },
              "step_identifier": {
                "id": "88ac5e6e-1c5c-4638-96e1-0d61221ad5bf"
              }
            }
          ]
        }
      ],
      "filters": {
        "collections": [
          {
            "id": "a1b6c97b-0af1-4791-bdc8-b5d0556004ae"
          }
        ],
        "content_types": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ],
        "languages": [
          {
            "id": "16ec3fdb-cb3d-42ea-a179-6fd682d4a25b"
          }
        ]
      }
    },
    "taxonomy": {
      "enabled": true,
      "actions": [
        {
          "action": "term_changed"
        }
      ],
      "filters": {
        "taxonomies": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ]
      }
    },
    "asset": {
      "enabled": true,
      "actions": [
        {
          "action": "deleted"
        }
      ]
    },
    "language": {
      "enabled": true,
      "actions": [
        {
          "action": "changed"
        },
        {
          "action": "created"
        }
      ],
      "filters": {
        "languages": [
          {
            "id": "99efc78f-af77-4535-a553-3ae2c5fd5385"
          }
        ]
      }
    }
  }
}

Enable a webhook

Enables a webhook specified by its internal ID.
PUT
https://manage.kontent.ai/v2/projects/{environment_id}/webhooks-vnext/{webhook_identifier}/enable

Request

Path parameters

environment_id
required · string
Identifies your environment.
webhook_identifier
required · string
Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .enableWebhook()
  .byId('5df74e27-1213-484e-b9ae-bcbe90bd5990')
  .toPromise();

Response

Status (204)
The specified webhook was enabled.
Empty response

Example responses

404
{
  "request_id": "|f5e9980562323e4b9b23588a141d323a.2774b2ca_",
  "error_code": 111,
  "message": "The requested webhook was not found."
}

Disable a webhook

Disables a webhook specified by its internal ID.
PUT
https://manage.kontent.ai/v2/projects/{environment_id}/webhooks-vnext/{webhook_identifier}/disable

Request

Path parameters

environment_id
required · string
Identifies your environment.
webhook_identifier
required · string
Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .disableWebhook()
  .byId('5df74e27-1213-484e-b9ae-bcbe90bd5990')
  .toPromise();

Response

Status (204)
The specified webhook was disabled.
Empty response

Example responses

404
{
  "request_id": "|f5e9980562323e4b9b23588a141d323a.2774b2ca_",
  "error_code": 111,
  "message": "The requested webhook was not found."
}

Delete a webhook

Delete a webhook specified by its internal ID.
DELETE
https://manage.kontent.ai/v2/projects/{environment_id}/webhooks-vnext/{webhook_identifier}

Request

Path parameters

environment_id
required · string
Identifies your environment.
webhook_identifier
required · string
Identifies a specific webhook by its internal ID (e.g., 5df74e27-1213-484e-b9ae-bcbe90bd5990).

Request samples

TypeScript
C#
cURL
// Tip: Find more about JS/TS SDKs at https://kontent.ai/learn/javascript
import { ManagementClient } from '@kontent-ai/management-sdk';

const client = new ManagementClient({
  environmentId: 'KONTENT_AI_ENVIRONMENT_ID',
  apiKey: 'KONTENT_AI_MANAGEMENT_API_KEY',
});

const response = await client
  .deleteWebhook()
  .byId('d53360f7-79e1-42f4-a524-1b53a417d03e')
  .toPromise();

Response

Status (204)
The specified webhook was deleted.
Empty response

Example responses

404
{
  "request_id": "|4917a91f0f3c1640a41e5afda87f57b5.9fa110d9_",
  "error_code": 111,
  "message": "The requested webhook was not found."
}
Copyright © 2026 Kontent.ai. All rights reserved.
  • Web
  • Privacy policy
  • Cookies policy
  • Consent settings
  • Security
  • GDPR