Webhooks

These are the operations. The event catalog, the payload shape, how to verify a delivery and what happens when yours stops answering are on Webhooks — this page is the endpoint reference for managing endpoints, not the guide to receiving from them.

Reading needs webhooks:read and writing needs webhooks:write. Neither can be held by an AI assistant's key: pointing a workspace's data at a new address is a thing a person does, or a system a person deployed.

Operations

GET /v1/webhooks/events

List webhook event types

Scope webhooks:read.

Every event an endpoint can subscribe to, with the object each one is about. Read this rather than hard-coding the list: an event added later appears here, and an endpoint that subscribed to everything receives it without being changed.

Answers

GET /v1/webhooks

List webhook endpoints

Scope webhooks:read.

The endpoints registered for this workspace, to see where events go and why one did not arrive.

Needs webhooks:read. A key issued with inquiries:read before this operation had a scope of its own is still accepted here, and that acceptance will be withdrawn: issue new keys with webhooks:read.

Answers

POST /v1/webhooks

Register a webhook endpoint

Scope webhooks:write. Idempotency-Key is required.

Register a URL and receive the signing secret, once.

The URL must be https and must resolve to a public host. Loopback, private ranges and bare IP addresses are refused here and again at every delivery, because a hostname that is public today can point somewhere else tomorrow.

events left out means every event, now and in future, which is what you want unless you have a reason not to. An explicit list is validated against the catalog and an unknown name is refused rather than dropped. page_slugs left out means every page in the workspace; events that are not about a page are only ever sent to an endpoint that covers all of them.

Idempotency-Key is required. Minting a credential is the one operation where a retried network timeout cannot be told apart from a request that never landed, and the only safe move without a key would be to create a second endpoint. A replay answers the same body with secret: null.

Five endpoints per workspace by default (409); your plan's number is webhook_endpoints in GET /usage.

Request body (required)

{
  "url": "https://example.com"
}

Answers

GET /v1/webhooks/{id}

Read one webhook endpoint

Scope webhooks:read. Another workspace's answers 404.

One endpoint's configuration and its delivery health. Never its signing secret.

Parameters

Answers

PATCH /v1/webhooks/{id}

Change a webhook endpoint

Scope webhooks:write. Another workspace's answers 404.

Change the URL, the events, the pages, the description, or switch the endpoint on and off. Send only what you want to change.

enabled: false is a pause: the endpoint and its signing secret survive, and events stop. That is what you want while a receiver is being redeployed: deleting the endpoint would destroy the secret every other environment is still using. enabled: true also clears the failure count, or the next single failure would switch it off again however long it had been working in between.

Events missed while an endpoint is off are not replayed.

Parameters

Request body (required)

Answers

DELETE /v1/webhooks/{id}

Delete a webhook endpoint

Scope webhooks:write. Another workspace's answers 404.

Deletes the endpoint, its queued deliveries and its delivery log. The signing secret goes with it and cannot be recovered.

To stop events without losing any of that, send enabled: false instead.

Parameters

Answers

POST /v1/webhooks/{id}/rotate-secret

Rotate a signing secret

Scope webhooks:write. Idempotency-Key is required. Another workspace's answers 404.

Replace the signing secret and receive the new one, once. The endpoint keeps its id, its URL and its subscriptions.

There is no grace window, and that is deliberate. Rotating an API key leaves the old one working for a while because many systems hold it and we are the ones verifying it. A signing secret is verified by one receiver you control, so a window in which two secrets both validate is a window in which a leaked secret still validates, which is the only reason anybody rotates one in a hurry. The old secret stops at once: paste the new one into your receiver, and the deliveries in between fail their signature check and are retried.

Idempotency-Key is required, for the same reason it is on registering an endpoint. A replay answers secret: null.

Parameters

Request body (optional)

Answers

GET /v1/webhooks/{id}/deliveries

List delivery attempts

Scope webhooks:read. Another workspace's answers 404.

One row per attempt, newest first: the exact body that was signed, the status your endpoint answered with, up to 512 bytes of that answer, how long it took, and why it failed when it did.

delivery_id is stable across every attempt of one occurrence, and is the value the X-BoltClaw-Delivery header carries. Key your idempotency off it.

Attempts are kept for 30 days. The reason for a failure is one of a fixed set of sentences, never your own server's words.

Parameters

Answers

POST /v1/webhooks/{id}/deliveries/{delivery_id}/redeliver

Send a delivery again

Scope webhooks:write. Accepts Idempotency-Key. Another workspace's answers 404.

Queue the same body again, signed afresh. The retry ladder starts over, and the body is the one that was frozen when the event happened, so your receiver sees the event it already knows how to deduplicate rather than a second, different fact.

Sixty redeliveries per workspace per hour (429). A paused endpoint is 409.

Parameters

Request body (optional)

Answers

POST /v1/webhooks/{id}/test

Send a test event

Scope webhooks:write. Accepts Idempotency-Key. Another workspace's answers 404.

Queue a webhook.test delivery to this one endpoint, signed exactly as a real event is, so you can prove your receiver verifies a signature before a real event arrives to tell you it does not.

It is sent whatever the endpoint has subscribed to and whatever pages it covers: a test you have to subscribe to first cannot tell you whether your subscription works. A paused endpoint is 409.

Parameters

Request body (optional)

Answers

Shapes

The objects these operations send and answer.

EmptyBody

This operation takes no fields. Send {}, or no body at all.

object.

Webhook

WebhookCreate

WebhookCreated

WebhookDeleted

WebhookDelivery

WebhookDeliveryList

WebhookEvent

An event an endpoint can subscribe to. GET /webhooks/events returns the live list with a description of each; read that rather than hard-coding this enum, because an event added later appears there first.

One of: conversation.message.created, social.inbox.item.created, social.post.published, social.post.failed, lead.created, referral.partner.applied, referral.partner.approved, referral.conversion.created, referral.commission.created, referral.bonus.created, referral.referrer.created, referral.referrer.conversion, referral.referrer.reward_earned, referral.referrer.payout_details_changed, referral.commission.reversed, referral.payout.paid, referral.grant.ready, referral.grant.fulfilled, referral.grant.cancelled, referral.grant.reversed, referral.referee.invite_ready, referral.risk.alert, referral.payout.sent, referral.payout.failed, referral.payout.returned, referral.payout.requested, referral.tax_form.signed, referral.tax_form.expiring, referral.invoice.issued, referral.invoice.disputed, referral.broadcast.sent, referral.partner.imported_claimed, referral.contest.ended, referral.milestone.reached, referral.waitlist.entry_created, referral.waitlist.position_changed, webhook.test.

WebhookEventType

WebhookEventTypeList

WebhookList

WebhookQueued

WebhookSecretRotated

WebhookTestQueued

WebhookUpdate

Send only the fields you want to change. An empty object is 400.