usend Docs
API endpoints

Webhooks

Create and manage webhooks, list deliveries and replay them.

See Webhooks for events, payloads and signature verification.

The webhook object

JSON
{
  "object": "webhook",
  "id": "4dd369bc-aa82-4ff3-97de-514ae3000ee0",
  "endpoint": "https://acme.com/webhooks/usend",
  "events": ["email.delivered", "email.bounced"],
  "enabled": true,
  "signing_secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
  "created_at": "2026-10-11T08:00:00.000Z"
}

Create a webhook

POST /webhooks

NameTypeRequiredDescription
endpointstringYesAn absolute http:// or https:// URL.
eventsstring[]YesAt least one event type: email.queued, email.scheduled, email.sent, email.delivered, email.delivery_delayed, email.bounced, email.complained, email.opened, email.clicked, email.failed, email.canceled, email.received, contact.unsubscribed.
cURL
curl -X POST https://api.usend.et/webhooks \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{
    "endpoint": "https://acme.com/webhooks/usend",
    "events": ["email.delivered", "email.bounced"]
  }'

Returns the webhook object, including signing_secret.

Retrieve a webhook

GET /webhooks/{id}

cURL
curl https://api.usend.et/webhooks/4dd369bc-aa82-4ff3-97de-514ae3000ee0 \
  -H "Authorization: Bearer us_123456789"

Returns the webhook object.

List webhooks

GET /webhooks

cURL
curl https://api.usend.et/webhooks \
  -H "Authorization: Bearer us_123456789"
Response
{
  "object": "list",
  "data": [
    {
      "object": "webhook",
      "id": "4dd369bc-aa82-4ff3-97de-514ae3000ee0",
      "endpoint": "https://acme.com/webhooks/usend",
      "events": ["email.delivered", "email.bounced"],
      "enabled": true,
      "signing_secret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw",
      "created_at": "2026-10-11T08:00:00.000Z"
    }
  ]
}

Update a webhook

PATCH /webhooks/{id}

NameTypeRequiredDescription
endpointstringNoA new URL.
eventsstring[]NoReplaces the subscribed events.
enabledbooleanNofalse pauses the webhook.
cURL
curl -X PATCH https://api.usend.et/webhooks/4dd369bc-aa82-4ff3-97de-514ae3000ee0 \
  -H "Authorization: Bearer us_123456789" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'

Returns the updated webhook object.

Delete a webhook

DELETE /webhooks/{id}

cURL
curl -X DELETE https://api.usend.et/webhooks/4dd369bc-aa82-4ff3-97de-514ae3000ee0 \
  -H "Authorization: Bearer us_123456789"
Response
{ "object": "webhook", "id": "4dd369bc-aa82-4ff3-97de-514ae3000ee0", "deleted": true }

List deliveries

GET /webhooks/{id}/deliveries

Lists the events sent to a webhook, newest first. Paginated. Deliveries are kept for 30 days.

NameTypeRequiredDescription
idstringYesThe webhook ID (path).
limitintegerNo1 to 100. Default 50.
afterstringNoReturn deliveries older than this delivery ID.
beforestringNoReturn deliveries newer than this delivery ID.
cURL
curl "https://api.usend.et/webhooks/4dd369bc-aa82-4ff3-97de-514ae3000ee0/deliveries?limit=20" \
  -H "Authorization: Bearer us_123456789"
Response
{
  "object": "list",
  "data": [
    {
      "id": "2b7c4a51-1f0e-4f6e-9c8a-7d2f3e9a6b10",
      "event_type": "email.delivered",
      "status": "succeeded",
      "attempts": 1,
      "response_status": 200,
      "last_error": null,
      "created_at": "2026-10-11T09:12:47.118Z",
      "delivered_at": "2026-10-11T09:12:47.402Z"
    }
  ],
  "has_more": false
}

status is pending, succeeded or failed. See Retries and replay.

Replay a delivery

POST /webhooks/{id}/deliveries/{delivery_id}/replay

Sends a delivery again with its original payload.

NameTypeRequiredDescription
idstringYesThe webhook ID (path).
delivery_idstringYesThe delivery ID (path).
cURL
curl -X POST https://api.usend.et/webhooks/4dd369bc-aa82-4ff3-97de-514ae3000ee0/deliveries/2b7c4a51-1f0e-4f6e-9c8a-7d2f3e9a6b10/replay \
  -H "Authorization: Bearer us_123456789"
Response
{}