Setting up webhooks

Webhooks are created, tested and monitored in the admin interface, under System settings → Webhooks. This guide is for organisation owners and admins who connect a receiver and keep it healthy.

Only members with the owner or admin role see the Webhooks section. The receiver itself is built separately; see Implementing a webhook receiver.

Create a webhook

1. Open System settings → Webhooks and choose New webhook.
2. Fill in the form:
   • Name: a label for your own records, such as "Search index (production)".
   • URL: the receiver's address. It must use https://; plain http:// is accepted only for localhost and 127.0.0.1.
   • Document type: core/article, core/planning-item or core/newswire. A webhook covers one type, so create one webhook per type.
   • Statuses: Specific statuses lists the statuses of the type's default workflow; tick at least one. Any status matches every status, which includes every save of a draft.
3. Choose Create.

The webhook delivers full payloads, and it starts disabled: nothing is sent until it is enabled.

Keep the secret

The dialog that follows creation shows the webhook's signing secret. This is the only time it is shown. Copy it into the receiver's secret store before choosing I've saved it.

The secret looks like wh_1a2b3c4d_ followed by 43 characters. The webhook's page shows the wh_1a2b3c4d_ part as the Signing prefix, which tells webhooks apart without exposing the secret. A secret cannot be rotated in place: to replace one, create a new webhook and revoke the old one.

Enable it and send a test

Open the webhook from the list. Turn on Enabled; the switch reads Deliveries active. Then choose Send test, which is available only while the webhook is enabled.

The test sends a webhook.test event with "document": null and "test": true, signed like any other delivery. A notification shows the HTTP status and the response time. A failed test is not retried: fix the receiver and send another.

Read the deliveries log

Recent events on the webhook's page lists one entry per event, newest first, 20 at a time; Load older events fetches more. Each entry shows:

• the outcome: success, retrying (more attempts are queued) or failed (no attempts left);
• the event type, the document id and version, and the event id;
• the number of attempts and when the latest one ran.

Expand an entry to see every attempt with its HTTP status, duration and error message, plus the first 4,096 characters of the response body. When a receiver redirects, the error names the status and the address it pointed to.

Replay an event

An event without a successful attempt has a Replay button. A replay sends the event again under the same event id, so a receiver that deduplicates treats it as a retry. Use it after fixing a receiver that ran out of retries.

A replay rebuilds the body in the webhook's payload mode, the same way as a first delivery: a full-mode replay reads the snapshot again and rebuilds the embedded media arrays, a compact one carries the envelope only. It carries a new occurredAt and sends document.title as null. A replay is a single attempt and is not retried. The button disappears once any attempt has succeeded.

Pause or revoke a webhook

Turn off Enabled to pause deliveries. Events that occur while a webhook is paused are never delivered, and retries that fall due while it is paused are dropped.

Revoke webhook stops all deliveries for good and cannot be undone. The admin interface changes nothing else on an existing webhook: to change its URL, document type or statuses, create a new one.

When the receiver's URL changes

A webhook's URL is fixed, and redirects are never followed. To move a receiver:

1. Deploy the receiver at its new address.
2. Create a webhook with the new URL and the same document type and statuses. Store its secret at the receiver.
3. Enable the new webhook and send a test.
4. Revoke the old webhook.

While both webhooks are active, each event is delivered twice, under the same event id but signed with different secrets. A receiver that accepts either secret during the overlap and deduplicates on the event id processes each event once.

Common problems

• Every test returns 401. The receiver holds the wrong secret, or it verifies a parsed and re-serialised body instead of the raw bytes.
• Attempts fail with a 3xx status. Register the address the redirect pointed to.
• Attempts time out. The receiver must answer within 10 seconds; it should acknowledge first and process afterwards.

Related pages

• Webhooks
• Receive your first webhook
• Webhook reference