Register an https URL that receives the events of every workspace in the organization, closed ones included while they exist, for the event types it subscribes to (as on POST /webhooks). Workspaces' own endpoints keep receiving theirs: an event goes to each matching endpoint of either kind. Each delivery's envelope names the workspace the event happened in (workspace_id) and that workspace's external_id as it is when the delivery is made (null when it has none); a workspace endpoint's envelope has no external_id. The response includes the signing_secret exactly once. Names and URLs are unique in the organization. At most 5 endpoints per organization: the next create is a 422 and creates nothing. One endpoint already receives every workspace's events, so add event types to an existing endpoint (update its events) instead of adding endpoints. Takes an organization key (ok_live_…) with organizations:write.
Parameters1 field
Field
Type
Description
idrequired
string · path
The organization's id (`org_…`), from `GET /whoami` or Organization → API.
Request body4 fields
Field
Type
Description
urlrequired
string
—
eventsrequired
enum | string[]
—
name
string
—
include_text
boolean
`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
Response · 201 fields11 fields
Field
Type
Description
objectrequired
string
—
idrequired
string
—
namerequired
string
—
urlrequired
string
—
eventsrequired
enum | string[]
—
statusrequired
enumenabled | disabled | suspended
—
include_text
boolean
`email.received` deliveries to this endpoint also carry the message's plain-text body as `text`, at most 64 KB (`text_truncated` says it was cut). Null for a copy of one of your own sends (`sent_by_us`), a message deleted since, or one with no plain-text part. Default false: metadata only. The text is read when each delivery is sent and is never kept with the event, so the deliveries log doesn't show it.
created_atrequired
string
—
updated_atrequired
string
—
backlog
object
The deliveries a flush would send. Each count stops at 10,001, which means more than 10,000. Only on `GET /webhooks/{id}`.
signing_secretrequired
string
The HMAC signing secret. Shown exactly once — store it now; it can never be retrieved again. Use it to verify the signature on every delivery to this endpoint.