--- title: "Webhook objects" slug: "webhook-objects" abstract: "The webhook JSON objects that interact with the Edge Admin API endpoint, for integrating XM and SitecoreAI publishing flows." --- # Webhook objects A webhook is a way for a service to provide other applications with real-time information. Webhooks trigger external builds of consuming applications when a publishing operation is complete. This topic describes the various JSON objects used within the webhooks endpoint of the Edge Admin API. ## Automatic deactivation of failed webhooks Sitecore regularly monitors the status of webhook execution and automatically disables a webhook that fails more than 10 consecutive attempts. A webhook is considered failed if it is doesn't respond within 30 seconds or less. When a webhook is executed, the result is logged in the `lastRuns` property. If the execution fails: 1. The system retrieves the previous execution results and checks if the past 9 executions have also failed. 2. If they have, the `disabled` property is set to `true`, thereby disabling the webhook. 3. A message is added to the `lastRuns` property that indicates that the webhook is disabled: `The webhook has failed the past 10 consecutive executions and is now disabled`. After you address the reasons for the webhook failure and ensure it can be handled properly on your end, you can manually restart it by sending a `PUT` request to the `/webhooks/{id}` endpoint and set the `disabled` property to `false`, as shown in the following example: ```json { "tenantId": "kgo-tenant", "label": "kgo webhook", "uri": "https://www.sitecore.com/", "method": "GET", "headers": { "x-header": "foo" }, "disabled": false } ``` ## WebhookEdit The properties used to create or update a webhook, when calling the `CreateWebhook` or `UpdateWebhook` [Admin endpoints](https://doc.sitecore.com/sai/en/developers/sitecoreai/experience-edge/experience-edge-apis/admin-rest-api.html "Admin API"). | Name | Type | Description | | --------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `label` | string | Describes the purpose of the webhook. | | `uri` | `Uri` | The URI to make the web request to. | | `method` | string | The HTTP method to use when making the web request. Must be `GET` or `POST`. | | `headers` | object | Custom headers to send when making the web request. Commonly used for authentication. | | `body` | string | The body to post when making the web request. Only populated if `ExecutionMode` is `OnEnd`. | | `bodyInclude` | string | Additional JSON object to include in the body of the webhook request. Only populated if `ExecutionMode` is `OnUpdate`. This field must be a valid JSON object. | | `createdBy` | string | The name of the user who created the webhook. | | `executionMode` | string | Determines how the webhook is executed. Must be one of the following options: `OnEnd`, `OnUpdate`. | Example: ```json { "label": "My new webhook", "uri": "https://www.mysite.com/hooks/edge-hook", "method": "POST", "headers": { "x-header": "bar" }, "body": "{\"rebuild\":\"true\"}", "createdBy": "anco", "executionMode": "OnEnd" } ``` ## Webhook Describes the webhook. | Name | Type | Description | | --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string | The identifier for this webhook. | | `tenantId` | string | The ID of the tenant this webhook belongs to. | | `label` | string | Describes the purpose of the webhook. | | `uri` | `Uri` | The URI to make the web request to. | | `method` | string | The HTTP method to use when making the web request. Must be `GET` or `POST`. | | `headers` | object | Custom headers to send when making the web request. Commonly used for authentication. | | `body` | string | The body to post when making the web request. Only populated if `ExecutionMode` is `OnEnd`. | | `bodyInclude` | string | An additional JSON object to include in the body of the webhook request. Can only be populated if `ExecutionMode` is `OnUpdate`. This field must be a valid JSON object. | | `createdBy` | string | The name of the user who created the webhook. | | `created` | `DateTimeOffset` | The timestamp when the webhook was created. | | `executionMode` | string | Determines how the webhook is executed. Must be one of the following options: `OnEnd`, `OnUpdate`. | | `lastRuns` | array of objects | The results of the latest executions of the webhook. The following table describes the `lastRuns` object. | ### The lastRuns object The `lastRuns` object can contain the following fields: | Name | Type | Description | | ----------- | -------------- | ------------------------------------------------- | | `timestamp` | `DateTimeOffset` | The timestamp when the execution log was created. | | `success` | Boolean | Indicates whether the webhook ran successfully. | | `message` | string | In case the webhook failed, the error message. | Example: ```json { "id": "5678", "tenantId": "acme-corp", "label": "webhook 29", "uri": "https://www.acme.com/hooks/edge-hook", "method": "POST", "headers": { "x-header": "bar" }, "body": "{"rebuild\":\"true\"}", "createdBy": "anco", "created": "2021-03-26T10:44:04.6107312+00:00", "executionMode": "OnEnd", "lastRuns": [ { "timestamp": "2024-05-16T10:10:53.825Z", "success": true }, { "timestamp": "2024-05-30T09:50:53.2134315+00:00", "success": false, "message": "Internal service error" } ], "disabled": false } ``` ## EntityUpdate Describes an entity that was updated and caused the webhook execution. | Name | Type | Description | | ------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | | `identifier` | string | The identifier of the entity. | | `entity_definition` | string | The definition of the entity. Only populated for an update operation. The possible values are:
| | `operation` | string | The type of operation executed: `update` or `delete`. | | `entity_culture` | string | The culture (language) version of the entity to update. | Example: ```json { "identifier": "B43D07BD61D5448F93238B6ACAD4F3C4", "entity_definition": "Item", "operation": "Update", "entity_culture": "en" } ``` ## WebHookRequest The body of a request made to a webhook endpoint that uses the `OnUpdate` execution mode. | Name | Type | Description | | --------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invocation_id` | GUID | Identifies the invocation of the webhook. Used to correlate across large counts of updates spanning across multiple webhook requests. | | `updates` | array of `EntityUpdate` | The entities that were updated and caused the webhook execution. | | `continues` | bool | Indicates whether there will be an additional request to continue sending more updates. This occurs when there are a large number of updates and they are split between multiple requests.

If the field is populated, this JSON object is merged into the body of the request with properties of the object being injected into the request body object. | Example: ```json { "invocation_id": "6a271d7b-92de-4d14-8002-8fc97a46c290", "updates": [ { "identifier": "B43D07BD61D5448F93238B6ACAD4F3C4", "entity_definition": "Item", "operation": "Update", "entity_culture": "en" }, { "identifier": "siteName", "entity_definition": "SiteInfo", "operation": "Update", "entity_culture": "all" }, { "identifier": "3CE9A090FB9B42BEB593F39BFCB1DE2B", "entity_definition": "Item", "operation": "Update", "entity_culture": "en" } ], "continues": false } ```