A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"plane": "product",
"description": "<string>",
"subscribed_events": [
"<string>"
],
"status": "enabled",
"consecutive_failures": 123,
"disabled_at": "2023-11-07T05:31:56Z",
"disabled_reason": "<string>",
"recent_failures": 123,
"created_at": "2023-11-07T05:31:56Z",
"secret": "<string>",
"environment": "live"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Register a webhook endpoint
Requires webhooks:manage. The endpoint is born in an environment and never leaves it: a test endpoint hears test traffic, a live one hears live traffic. Facts about the organization itself (organization.created, member.invited) carry no environment and go to the live endpoints — an organization has one real existence, and the test environment is where the customer plane is rehearsed, not where the organization is.
The signing secret comes back here because this is the moment you need it, but unlike an API key it is re-showable: losing this response is not losing the secret.
Registering an audit endpoint additionally requires audit:deliver (403 without it) and a plan that carries the capability (402 without it). Its deliveries carry an actor object the product plane never sends, and a plan that stops carrying it stops the deliveries — the trail itself is recorded and kept on every plan.
A valid request URL is required to generate request examples{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"url": "<string>",
"plane": "product",
"description": "<string>",
"subscribed_events": [
"<string>"
],
"status": "enabled",
"consecutive_failures": 123,
"disabled_at": "2023-11-07T05:31:56Z",
"disabled_reason": "<string>",
"recent_failures": 123,
"created_at": "2023-11-07T05:31:56Z",
"secret": "<string>",
"environment": "live"
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Authorizations
A staff session token, uk_st_…. Minted by sign-up, sign-in or the two-factor exchange. Only a 401 means it is spent; not_a_member (403) is about the organization named in X-Organization-Id and leaves the token good for the others.
Headers
The organization the caller is acting on — the org_… code that appears in the panel URL. It identifies; the membership JOIN is what authorizes, so a forged code reads nothing: the answer is not_a_member (403), which does not mean the session is over. Absent, the session's default organization answers, or — if that membership was revoked while the session was open — any other one the caller still holds.
Body
https:// only. Deliveries never cross plaintext, and a redirect is refused rather than followed — register the final address.
live, test product (the default, and what an omitted field means) is the event catalogue. audit is the staff audit trail: it needs audit:deliver — owner-only, and deliberately not webhooks:manage — and a plan that carries the capability. An audit endpoint takes no subscribed_events and is registered in the live environment, because the trail belongs to the organization and carries staff actions from both environments.
product, audit A label, so a list of three endpoints says which is which.
Types from GET /v1/organization/webhooks/events. Omit or leave empty for every deliverable event. Refused on the audit plane: a record with the interesting lines filtered out reads as nothing having happened.
Response
Created. secret is what deliveries are signed with.
Where deliveries are POSTed. https:// only.
Which fan-out feeds this endpoint. product is the event catalogue, filtered by subscribed_events. audit is the staff audit trail — every action somebody in the panel performed, with the actor on the body. Set when the endpoint is registered and never afterwards: moving an endpoint between planes would be a way around the permission and the plan that guard the second one.
product, audit Types from the published catalogue. Empty means every deliverable event — a new type then starts arriving without anything being changed here.
disabled is either your decision or the auto-disable after sustained failure. A disabled endpoint is queued nothing.
enabled, disabled Deliveries that spent every attempt, back to back. Any success resets it.
Deliveries that gave up in the last 24 hours.
The signing secret (uk_wh_…). Re-showable at /secret.
live, test