Webhooks
A webhook endpoint is an HTTPS URL that receives signed events. Every endpoint here needs webhooks:manage. Events, signatures and retries are explained in Webhooks.
The webhook object
Section titled “The webhook object”| Field | Type | Description |
|---|---|---|
id |
string | whk_… |
url |
string | The endpoint. |
events |
string[] | Subscribed event types. |
enabled |
boolean | Disabled endpoints receive nothing. |
description |
string or null | Your note. |
createdAt, updatedAt |
string |
The delivery object:
| Field | Type | Description |
|---|---|---|
id |
string | dlv_… |
webhookId |
string | |
eventId |
string | evt_…, also sent as SMSFabric-Event-Id. |
eventType |
string | Such as message.delivered. |
status |
string | pending, succeeded or failed. |
attempts |
integer | Attempts made, up to 8. |
lastStatusCode |
integer or null | Your endpoint’s last HTTP status. |
lastError |
string or null | Such as HTTP 500 or timeout. |
nextAttemptAt |
string or null | When the next retry runs. |
deliveredAt |
string or null | When your endpoint answered 2xx. |
createdAt |
string |
List endpoints
Section titled “List endpoints”/v1/webhookswebhooks:manageReturns every endpoint in one page (nextCursor: null).
curl https://api.smsfabric.com/v1/webhooks \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "data": [ { "id": "whk_p9s2v5y8b1e4h7k0n3q6t9w2", "url": "https://acme.example/hooks/smsfabric", "events": ["message.delivered", "message.failed", "message.received"], "enabled": true, "description": "Order notifications", "createdAt": "2026-11-01T08:00:00.000Z", "updatedAt": "2026-11-01T08:00:00.000Z" } ], "nextCursor": null}Create an endpoint
Section titled “Create an endpoint”/v1/webhookswebhooks:manageReturns 201 with the endpoint and its signingSecret, shown only this once. Supports Idempotency-Key. Audited as webhook.created.
| Body field | Type | Required | Description | Constraints |
|---|---|---|---|---|
url |
string | Yes | Where events are posted. | https, a public address; up to 2,048 characters. |
events |
string[] | Yes | Event types to receive. | At least one of: message.queued, message.sent, message.delivered, message.failed, message.received, device.online, device.offline, verification.approved, verification.expired, verification.blocked, campaign.started, campaign.completed. |
description |
string | No | Your note. | Up to 255 characters. |
curl https://api.smsfabric.com/v1/webhooks \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url": "https://acme.example/hooks/smsfabric", "events": ["message.delivered", "message.failed", "message.received"], "description": "Order notifications"}'{ "id": "whk_p9s2v5y8b1e4h7k0n3q6t9w2", "url": "https://acme.example/hooks/smsfabric", "events": ["message.delivered", "message.failed", "message.received"], "enabled": true, "description": "Order notifications", "createdAt": "2026-11-19T13:10:00.000Z", "updatedAt": "2026-11-19T13:10:00.000Z", "signingSecret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}| Error | When |
|---|---|
400 ssrf_blocked |
The URL is not https, or its host resolves to a private, loopback or link-local address. |
400 validation_failed |
No events, or an unknown event type. |
403 plan_limit_reached |
Your plan has no room for another endpoint. See Plans. |
Update an endpoint
Section titled “Update an endpoint”/v1/webhooks/:idwebhooks:manageAll fields optional: url, events, enabled and description, with the create constraints. A new url is checked again. Returns the endpoint (without the secret). Audited as webhook.updated.
curl -X PATCH https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2 \ -H "X-Api-Key: $SMSFABRIC_API_KEY" \ -H "Content-Type: application/json" \ -d '{"enabled": false}'Delete an endpoint
Section titled “Delete an endpoint”/v1/webhooks/:idwebhooks:manageReturns 204. Audited as webhook.deleted.
curl -X DELETE https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2 \ -H "X-Api-Key: $SMSFABRIC_API_KEY"List deliveries
Section titled “List deliveries”/v1/webhooks/:id/deliverieswebhooks:manageDelivery attempts for one endpoint, newest first, paginated with limit and cursor.
curl "https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2/deliveries?limit=1" \ -H "X-Api-Key: $SMSFABRIC_API_KEY"{ "data": [ { "id": "dlv_f3i6l9o2r5u8x1a4d7g0j3m6", "webhookId": "whk_p9s2v5y8b1e4h7k0n3q6t9w2", "eventId": "evt_c7e9g2i4k6m8o1q3s5u7w9y2", "eventType": "message.delivered", "status": "pending", "attempts": 2, "lastStatusCode": 503, "lastError": "HTTP 503", "nextAttemptAt": "2026-11-19T10:21:09.000Z", "deliveredAt": null, "createdAt": "2026-11-19T10:15:09.460Z" } ], "nextCursor": "ZGx2X2YzaTZsOW8ycjV1OHgxYTRkN2cwajNtNg"}Replay a delivery
Section titled “Replay a delivery”/v1/webhooks/:id/deliveries/:deliveryId/replaywebhooks:manageQueues the same event again, with the same event id and a fresh signature. Returns 202 with the delivery (status: "pending").
curl -X POST https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2/deliveries/dlv_f3i6l9o2r5u8x1a4d7g0j3m6/replay \ -H "X-Api-Key: $SMSFABRIC_API_KEY"Send a test event
Section titled “Send a test event”/v1/webhooks/:id/testwebhooks:manageSends a webhook.test event to this endpoint, signed like any other. Returns 202 with the new delivery.
curl -X POST https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2/test \ -H "X-Api-Key: $SMSFABRIC_API_KEY"The body your endpoint receives:
{ "id": "evt_e9g2i4k6m8o1q3s5u7w9y2a4", "type": "webhook.test", "createdAt": "2026-11-19T13:12:00.000Z", "orgId": "org_n5q8t1w4z7c0f3i6l9o2r5u8", "data": { "message": "This is a test event from SMSFabric." }}Listen for events (development)
Section titled “Listen for events (development)”/v1/webhooks/listenwebhooks:manageA development tool: a server-sent event stream of your organization’s webhook events as they happen, over a connection your machine opens, so you need no public URL. The CLI (smsfabric listen) and the SDK’s webhooks.listen() use it. It carries every event your organization produces, whether or not an endpoint subscribes to it. Works with an API key or a user token. Audited as webhook.listen_started.
| Query parameter | Type | Required | Description |
|---|---|---|---|
events |
string | No | Comma-separated event types, such as message.sent,message.delivered. Omit for every event. An unknown type returns 400 validation_failed. |
curl -N "https://api.smsfabric.com/v1/webhooks/listen?events=message.delivered,message.failed" \ -H "X-Api-Key: $SMSFABRIC_API_KEY"The answer is 200 with Content-Type: text/event-stream:
event: readydata: {"listenerId":"lsn_3f0b8c1e-7a4d-4e52-9b6a-0c2d1e8f9a47","events":["message.delivered","message.failed"],"expiresAt":"2026-11-19T13:05:00.000Z"}
: ping
event: eventid: evt_c7e9g2i4k6m8o1q3s5u7w9y2data: {"id":"evt_c7e9g2i4k6m8o1q3s5u7w9y2","type":"message.delivered","createdAt":"2026-11-19T13:01:12.000Z","orgId":"org_n5q8t1w4z7c0f3i6l9o2r5u8","data":{…}}
event: rotatedata: {}| Frame | Contents |
|---|---|
ready |
First frame: listenerId (lsn_…), events (empty means every event) and expiresAt, when the server ends this stream. |
event |
One webhook event. id is the event id; data is byte for byte the JSON body an endpoint receives, so you can sign and forward it unchanged. Verify messages are redacted as in webhooks. |
rotate |
Sent 10 seconds before the stream ends. Open the next stream now, and close this one once the new one sends ready. An event seen on both streams has the same id. |
: ping |
A comment line every 15 seconds that keeps idle connections open. Ignore it. |
How the stream behaves:
- Lifetime. The server ends each stream after 5 minutes, so a revoked key or a suspended organization stops receiving within that time.
- No replay. Events published while no stream is connected are not stored and not replayed.
- No signature. Frames are not signed, because the stream itself is authenticated. The CLI signs what it forwards with its own secret.
- Slow readers. A client that stops reading is disconnected once 1 MiB is waiting for it.
For production, register an endpoint: it gets signatures, retries for about 24 hours and a delivery log.
| Error | When |
|---|---|
400 validation_failed |
events names an unknown event type. |
403 missing_permission |
The key or user lacks webhooks:manage. |
429 too_many_listeners |
Your organization already has 5 streams open. Retry-After says when a lost stream frees its slot (within 45 seconds); a stream you close frees it at once. |
429 rate_limited |
More than 30 streams opened in a minute by one key or user. |
Errors arrive as a normal application/problem+json answer, before the stream starts.