Webhooks API
Register webhook endpoints to receive real-time notifications about message events.
GET /v1/webhooks
List all registered webhook endpoints for the authenticated organization.
cURL
curl https://api.yoursend.dev/v1/webhooks \
-H "Authorization: Bearer ys_live_..."
Response
{
"webhooks": [
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"url": "https://example.com/webhooks/yoursend",
"events": ["message.sent", "message.delivered", "message.failed"],
"is_active": true,
"created_at": "2026-01-15T09:30:00.000Z"
}
]
}POST /v1/webhooks
Register a new webhook endpoint. Returns the HMAC signing secret — store it securely, it is only shown once.
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | HTTPS endpoint URL |
events | string[] | No | Events to subscribe to. Defaults to message.sent, message.delivered, message.failed. |
cURL
curl -X POST https://api.yoursend.dev/v1/webhooks \
-H "Authorization: Bearer ys_live_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/webhooks/yoursend",
"events": ["message.sent", "message.delivered", "message.failed", "message.bounced"]
}'
Response (201)
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"url": "https://example.com/webhooks/yoursend",
"events": ["message.sent", "message.delivered", "message.failed", "message.bounced"],
"is_active": true,
"created_at": "2026-01-15T09:30:00.000Z",
"secret": "whsec_a1b2c3d4e5f6..."
}Important: The secret is only returned at creation. Store it securely to verify webhook signatures. See the verification guide.
PATCH /v1/webhooks/:id
Update a webhook endpoint's URL, events, or active status. All fields are optional — only include what you want to change.
| Field | Type | Description |
|---|---|---|
url | string | New endpoint URL |
events | string[] | Replace subscribed events |
is_active | boolean | Enable or disable the webhook |
cURL — update events
curl -X PATCH https://api.yoursend.dev/v1/webhooks/d290f1ee-... \
-H "Authorization: Bearer ys_live_..." \
-H "Content-Type: application/json" \
-d '{
"events": ["message.delivered", "message.failed", "message.bounced", "message.opened"]
}'
cURL — disable
curl -X PATCH https://api.yoursend.dev/v1/webhooks/d290f1ee-... \
-H "Authorization: Bearer ys_live_..." \
-H "Content-Type: application/json" \
-d '{ "is_active": false }'
Response
{
"id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"url": "https://example.com/webhooks/yoursend",
"events": ["message.delivered", "message.failed", "message.bounced", "message.opened"],
"is_active": true,
"created_at": "2026-01-15T09:30:00.000Z"
}DELETE /v1/webhooks/:id
Permanently delete a webhook endpoint.
cURL
curl -X DELETE https://api.yoursend.dev/v1/webhooks/d290f1ee-... \
-H "Authorization: Bearer ys_live_..."
Response
{ "deleted": true }Webhook Events
| Event | Description | Channels |
|---|---|---|
message.sent | Message accepted and sent to provider | Email, SMS, Voice |
message.delivered | Message confirmed delivered | Email, SMS, Voice |
message.opened | Recipient opened the email | |
message.clicked | Recipient clicked a link | |
message.bounced | Email bounced (hard or soft) | |
message.failed | Delivery failed or complaint received | Email, SMS, Voice |
otp.verified | OTP code verified successfully | Email, SMS, Voice |
otp.expired | OTP expired before verification | Email, SMS, Voice |
contact.suppressed | Contact auto-suppressed (bounce/complaint) | |
blast.completed | Bulk email blast finished | |
email.received | Inbound email received |