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.

Note

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:

  1. The system retrieves the previous execution results and checks if the previous 9 executions have also failed.

  2. If this is the case, the Disabled property is set to true and the webhook is automatically disabled.

  3. The following message is added to the lastRuns 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:

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

GET

/webhooks

Lists all webhooks.

GET

/webhooks/<identifier>

Shows a webhook with a specific identifier.

POST

/webhooks/<identifier>

Creates a webhook.

Note

You must use an HTTPS URI, not HTTP.

PUT

/webhooks/<identifier>

Updates a webhook with a specific identifier.

DELETE

/webhooks/<identifier>

Deletes a webhook with a specific identifier.

Do you have some feedback for us?

If you have suggestions for improving this article,