Skip to main content
PUT
Register or change the webhook

Authorizations

Authorization
string
header
required

The agency's secret key, sent as Authorization: Bearer <key>. One key per agency.

Body

application/json

The agency's webhook: where to send events, and which.

url
string<uri>
required

HTTPS on port 443. Put your own agency id in it: we treat it as opaque.

Required string length: 1 - 2083
events
string[]
required

Event types to send. ["*"] means all, including future ones, and wins over named types. POST /webhook/test always sends webhook.test.

Required array length: 1 - 50 elements
secret
string | null

Leave out on the first call and we generate one. Send one only to rotate: we sign with old and new for 24 hours.

Pattern: ^whsec_[A-Za-z0-9+/]{32,86}={0,2}$

Response

The registration. secret appears only when we generated or changed it.

The agency's webhook registration.

url
string
required

Where we send events.

events
string[]
required

The event types we send.

status
enum<string>
required

active: we deliver to it. disabled: switched off after a 410 or 5 days of failures; register again to switch it back on.

Available options:
active,
disabled
disabled_reason
string | null

Why it was switched off.

secret
string | null

Returned only when we generated or changed it. Store it.