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:

The system retrieves the previous execution results and checks if the past 9 executions have also failed.
If they have, the disabled property is set to true, thereby disabling the webhook.
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:

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

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:

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

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

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

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

If you have suggestions for improving this article, let us know!