Admin Webhooks API
You use the Admin Webhooks API to execute webhooks on external services.
Webhooks execution modes
A webhook is a method provided by the delivery service to make requests to web applications, such as rebuilding or initiating a site build for a static site generator (SSG).
The content delivery feature implements different execution modes which determine how and when to execute the webhooks.
OnEnd
OnEnd
is the default execution mode. In this mode, the webhook executes at the end of the publishing job after caches are purged. If the webhook definition includes a body, it is sent verbatim as the body of the webhook request. You can set a custom header on the webhook definition to change the content type of the request if the body is anything other than plain text (such as JSON or XML).
Requests to the webhook endpoint are debounced to reduce the number of requests to the endpoint and smooth over several small changes.
OnUpdate
OnUpdate
works the same way as OnEnd
but includes into the body of the webhook request the entity changes made that caused the webhook to execute. This mode does not allow a custom body on the webhook definition.
To avoid sending large requests, the entity changes are sent in batches across several webhook requests. Each batch is de-duplicated so that repeat events are not sent in a single request. The body sent is in JSON format. You can include JSON data into the body by populating the bodyInclude
field of the webhook definition.
Automatic deactivation of failing webhooks
The automatic deactivation feature monitors the status of webhook execution and disables any webhook that fails 10 consecutive times.
A webhook is considered to have failed when it takes longer than 30 seconds to respond.
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 previous 9 executions have also failed.
-
If this is the case, the
Disabled
property is set totrue
and the webhook is automatically disabled. -
The following
message
is added to thelastRuns
property, indicating that the webhook was disabled:The webhook has failed the past 10 consecutive executions and is now disabled.
Reactivate a webhook
If needed, you can manually reactivate a webhook after you address the reasons why it failed.
To do so, send a PUT
request to the /webhooks/<identifier>
endpoint (for example, /webhooks/97261f96-2b43-4e25-a925-5bc56194f1b1
) 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
}
Endpoints
All the following routes are relative to the base route of the admin endpoint:
Method |
URL |
Description |
---|---|---|
|
Lists all webhooks. | |
|
Shows a webhook with a specific identifier. | |
|
Creates a webhook. Note You must use an HTTPS URI, not HTTP. | |
|
Updates a webhook with a specific identifier. | |
|
Deletes a webhook with a specific identifier. |