Create an organization webhook endpoint

Create an organization webhook endpoint

POST/api/v1/organizations/{id}/webhooks

POST /organizations/{id}/webhooks
curl -X POST 'https://www.unitpost.com/api/v1/organizations/org_123/webhooks' \
  -H 'Authorization: Bearer YOUR_ORG_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com/webhooks/unitpost",
    "events": [
      "email.delivered",
      "email.bounced"
    ]
  }'
Response · 201
{
  "object": "webhook",
  "id": "id_123",
  "name": "Example",
  "url": "https://example.com",
  "events": [
    "email.sent"
  ],
  "status": "enabled",
  "include_text": false,
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "backlog": {
    "queued": 0,
    "failed": 0
  },
  "signing_secret": "string"
}

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
FieldTypeDescription
idrequiredstring · pathThe organization's id (`org_…`), from `GET /whoami` or Organization → API.
Request body4 fields
FieldTypeDescription
urlrequiredstring—
eventsrequiredenum | string[]—
namestring—
include_textboolean`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
FieldTypeDescription
objectrequiredstring—
idrequiredstring—
namerequiredstring—
urlrequiredstring—
eventsrequiredenum | string[]—
statusrequiredenumenabled | disabled | suspended—
include_textboolean`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_atrequiredstring—
updated_atrequiredstring—
backlogobjectThe deliveries a flush would send. Each count stops at 10,001, which means more than 10,000. Only on `GET /webhooks/{id}`.
signing_secretrequiredstringThe 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.
201401403404409422429

Search docs and guides

Search the docs and product guides.