Webhooks

List webhook endpoints

GET/api/v1/webhooks

GET /webhooks
curl -X GET 'https://www.unitpost.com/api/v1/webhooks' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "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
      }
    }
  ]
}

Retrieve a list of your webhook endpoints, cursor-paginated, with each endpoint's URL, subscribed events, and status. Signing secrets are never returned here — they're shown exactly once by Create a webhook endpoint. Check an endpoint's wiring end-to-end with Send a test event. Requires the webhooks:read capability.

Parameters3 fields
FieldTypeDescription
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
Response · 200 fields10 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}`.
200401403422

Create a webhook endpoint

POST/api/v1/webhooks

POST /webhooks
curl -X POST 'https://www.unitpost.com/api/v1/webhooks' \
  -H 'Authorization: Bearer YOUR_API_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 to receive event notifications (deliveries, bounces, opens, clicks, and more) and choose which events it subscribes to. The response includes the signing_secret exactly once — store it now, as it can never be retrieved again; use it to verify each delivery's signature. Confirm the endpoint works with Send a test event, and adjust its URL or events later with Update a webhook endpoint. Requires the webhooks:manage capability.

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.
201401403409422

Retrieve a webhook endpoint

GET/api/v1/webhooks/{id}

GET /webhooks/{id}
curl -X GET 'https://www.unitpost.com/api/v1/webhooks/wh_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "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
  }
}

Retrieve a single webhook endpoint by id — its URL, subscribed events, and status. The signing secret is never included; it's returned exactly once when the endpoint is created. backlog counts the deliveries Deliver the backlog would send: queued while the endpoint was paused, and failed. Requires the webhooks:read capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields10 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}`.
200401403404503

Update a webhook endpoint

PATCH/api/v1/webhooks/{id}

PATCH /webhooks/{id}
curl -X PATCH 'https://www.unitpost.com/api/v1/webhooks/wh_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      "email.delivered"
    ]
  }'
Response · 200
{
  "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
  }
}

Update a webhook endpoint's url, subscribed events, name, and/or status (use status to pause and re-enable deliveries without deleting the endpoint). The signing secret is never changed by an update. Verify your changes with Send a test event. Requires the webhooks:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body5 fields
FieldTypeDescription
urlstring—
eventsenum | string[]—
namestring—
statusenumenabled | disabled—
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 · 200 fields10 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}`.
200401403404409422

Delete a webhook endpoint

DELETE/api/v1/webhooks/{id}

DELETE /webhooks/{id}
curl -X DELETE 'https://www.unitpost.com/api/v1/webhooks/wh_123' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'

Permanently delete a webhook endpoint and its delivery log. Deliveries stop immediately. The operation is idempotent — deleting an already-deleted endpoint still returns 204. To stop deliveries temporarily instead, set status via Update a webhook endpoint. Requires the webhooks:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
204401403

Rotate a webhook's signing secret

POST/api/v1/webhooks/{id}/rotate-secret

POST /webhooks/{id}/rotate-secret
curl -X POST 'https://www.unitpost.com/api/v1/webhooks/wh_123/rotate-secret' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "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",
  "previous_secret_expires_at": "2026-01-01T00:00:00.000Z"
}

Mint a new signing secret for the endpoint. The response carries the new signing_secret exactly once, as Create a webhook endpoint does. For 24 hours (until previous_secret_expires_at) every delivery is signed with the new and the old secret, so switch your receiver to the new one inside that window without dropping a delivery. Rotating again inside the window retires the older secret at once. Requires the webhooks:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields1 field
FieldTypeDescription
previous_secret_expires_atrequiredstringUntil this time deliveries are signed with the new AND the old secret, so switch your receiver to the new one before then.
200401403404409

List a webhook's deliveries

GET/api/v1/webhooks/{id}/deliveries

GET /webhooks/{id}/deliveries
curl -X GET 'https://www.unitpost.com/api/v1/webhooks/wh_123/deliveries' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "webhook_delivery",
      "id": "id_123",
      "svix_id": "svix_123",
      "webhook_id": "webhook_123",
      "event_id": "event_123",
      "event_type": "string",
      "status": "pending",
      "attempt": 0,
      "response_status": 0,
      "error": "string",
      "scheduled_at": "2026-01-01T00:00:00.000Z",
      "next_attempt_at": "2026-01-01T00:00:00.000Z",
      "delivered_at": "2026-01-01T00:00:00.000Z",
      "event_created_at": "2026-01-01T00:00:00.000Z",
      "data": {}
    }
  ]
}

The endpoint's delivery log, newest first and cursor-paginated: one row per event delivered (or being delivered) to it, with its status, attempts, your endpoint's last HTTP status and error, and the event's type and data. Use it to see why deliveries fail; Send a test event probes the endpoint without adding a row. Narrow it with status and event_type. A filter value it can't apply (a typo, an unknown id) is ignored and named in the Unitpost-Warning header, and the answer is the one without it; send Unitpost-Strict: true to have it refused instead. Requires the webhooks:read capability.

Parameters6 fields
FieldTypeDescription
idrequiredstring · path—
limitinteger · queryMax rows to return (default 20, max 100).
afterstring · queryReturn rows after this id (forward paging).
beforestring · queryReturn rows before this id (backward paging).
statusstring · queryOne or more delivery statuses, comma-separated: `pending`, `queued`, `retrying`, `succeeded`, `failed`, `exhausted` (e.g. `failed,exhausted`).
event_typestring · queryOnly deliveries of this event type, e.g. `email.bounced`.
Response · 200 fields15 fields
FieldTypeDescription
objectrequiredenumwebhook_delivery—
idrequiredstringThe delivery id (`msg_…`).
svix_idrequiredstringThe `svix-id` header this delivery's requests carried; retries reuse it, so dedupe on it.
webhook_idrequiredstring—
event_idrequiredstringThe event (`evt_…`). The delivered payload's `event_id` is the same id without the `evt_` prefix.
event_typerequiredstring—
statusrequiredenumpending | queued | retrying | succeeded | failed | exhausted`queued`: held while the endpoint is disabled. `retrying`: an attempt failed and another is scheduled at `next_attempt_at`. `exhausted`: every retry failed.
attemptrequiredintegerAttempts made so far.
response_statusrequiredintegerYour endpoint's last HTTP status, or null before an attempt or on a network error.
errorrequiredstring—
scheduled_atrequiredstring—
next_attempt_atrequiredstring—
delivered_atrequiredstring—
event_created_atrequiredstring—
datarequiredobjectThe event's `data`, as delivered.
200401403404422

Replay a delivery

POST/api/v1/webhooks/{id}/deliveries/{delivery}/replay

POST /webhooks/{id}/deliveries/{delivery}/replay
curl -X POST 'https://www.unitpost.com/api/v1/webhooks/wh_123/deliveries/msg_123/replay' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 202
{
  "object": "webhook_delivery_replay",
  "webhook_id": "webhook_123",
  "delivery_id": "delivery_123",
  "replayed": true
}

Deliver one event to the endpoint again, as the dashboard's Replay does. The same event goes out with the same id, so a receiver that dedupes on it treats the replay as the delivery it already has. The webhook must be enabled: re-enable a disabled or suspended one with Update a webhook endpoint first. Find deliveries with List a webhook's deliveries. Takes no body. Requires the webhooks:manage capability.

Parameters2 fields
FieldTypeDescription
idrequiredstring · path—
deliveryrequiredstring · pathThe delivery's id (`msg_…`).
Response · 202 fields4 fields
FieldTypeDescription
objectrequiredenumwebhook_delivery_replay—
webhook_idrequiredstring—
delivery_idrequiredstring—
replayedrequiredenumtrue—
202400401403404409422429502

Deliver a webhook's backlog

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

POST /webhooks/{id}/flush
curl -X POST 'https://www.unitpost.com/api/v1/webhooks/wh_123/flush' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "include_failed": true
  }'
Response · 202
{
  "object": "webhook_flush",
  "webhook_id": "webhook_123",
  "flushed": 0
}

Deliver the deliveries held while the webhook was suspended (queued), as the dashboard's "Retry queued" does; with include_failed also the ones that failed for good (failed, exhausted). The webhook must be enabled: re-enable it with Update a webhook endpoint first. Re-enabling never delivers the backlog on its own. Requires the webhooks:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Request body1 field
FieldTypeDescription
include_failedbooleanAlso deliver the `failed` and `exhausted` deliveries again. Default false: only the `queued` ones (held while the webhook was suspended).
Response · 202 fields3 fields
FieldTypeDescription
objectrequiredenumwebhook_flush—
webhook_idrequiredstring—
flushedrequiredintegerHow many deliveries were handed back for delivery (0 when the backlog was empty).
202400401403404409422429502

Send a test event

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

POST /webhooks/{id}/test
curl -X POST 'https://www.unitpost.com/api/v1/webhooks/wh_123/test' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0'
Response · 200
{
  "object": "webhook_test",
  "delivered": false,
  "response_status": 0,
  "event_type": "string",
  "error": "string"
}

Fire a sample event at the endpoint synchronously and return the receiver's response so you can debug your handler end-to-end. The probe is signed exactly like a real delivery (verify it the same way) but is not persisted to the delivery log. Configure the endpoint itself with Update a webhook endpoint. Requires the webhooks:manage capability.

Parameters1 field
FieldTypeDescription
idrequiredstring · path—
Response · 200 fields5 fields
FieldTypeDescription
objectrequiredenumwebhook_test—
deliveredrequiredbooleanWhether the endpoint accepted the probe (2xx).
response_statusrequiredintegerThe HTTP status the endpoint returned, or null on a transport error.
event_typerequiredstringThe sample event type that was sent.
errorrequiredstringA transport/error message when delivery failed, else null.
200401403404

Search docs and guides

Search the docs and product guides.