Skip to main content
POST
Register a webhook

Headers

Idempotency-Key
string<uuid>
required

Client-generated unique key per operation intent (UUID). Same key + identical body replays the original response; same key + different body returns 409.

Body

application/json
name
string
required

A name to help you recognise this subscription.

Maximum string length: 255
url
string<uri>
required

HTTPS endpoint that deliveries are POSTed to.

event
string
required

The event type to subscribe to. Must be a known type from GET /webhooks/event_types.

description
string | null
Maximum string length: 1000
api_version
string | null

Pin a payload API version.

Maximum string length: 50
custom_headers
object

Custom headers sent with each delivery. Values are stored write-only and never returned.

Response

webhook_id
string<uuid>
required

Platform-assigned stable identifier.

name
string
required

Human-readable name for the subscription.

url
string<uri>
required

HTTPS endpoint deliveries are POSTed to.

event
string
required

The event type this subscription receives.

status
enum<string>
required
Available options:
ACTIVE,
PAUSED,
FAILED
custom_header_names
string[]
required

Names of configured custom headers. Header values are never returned.

failure_count
number
required

Consecutive delivery failures since the last success.

created_at
string<date-time>
required
updated_at
string<date-time>
required
secret
string
required

The signing secret. Shown only on creation and rotation — store it securely, it is never returned again.

description
string | null
api_version
string | null

Pinned payload API version.

last_failure_at
string<date-time> | null
last_success_at
string<date-time> | null
last_status_code
number | null
last_delivery_at
string<date-time> | null