Skip to content

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.

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
GET/v1/webhookswebhooks:manage

Returns every endpoint in one page (nextCursor: null).

Terminal window
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
}
POST/v1/webhookswebhooks:manage

Returns 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.
Terminal window
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.
PATCH/v1/webhooks/:idwebhooks:manage

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

Terminal window
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/v1/webhooks/:idwebhooks:manage

Returns 204. Audited as webhook.deleted.

Terminal window
curl -X DELETE https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2 \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
GET/v1/webhooks/:id/deliverieswebhooks:manage

Delivery attempts for one endpoint, newest first, paginated with limit and cursor.

Terminal window
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"
}
POST/v1/webhooks/:id/deliveries/:deliveryId/replaywebhooks:manage

Queues the same event again, with the same event id and a fresh signature. Returns 202 with the delivery (status: "pending").

Terminal window
curl -X POST https://api.smsfabric.com/v1/webhooks/whk_p9s2v5y8b1e4h7k0n3q6t9w2/deliveries/dlv_f3i6l9o2r5u8x1a4d7g0j3m6/replay \
-H "X-Api-Key: $SMSFABRIC_API_KEY"
POST/v1/webhooks/:id/testwebhooks:manage

Sends a webhook.test event to this endpoint, signed like any other. Returns 202 with the new delivery.

Terminal window
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." }
}
GET/v1/webhooks/listenwebhooks:manage

A 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.
Terminal window
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: ready
data: {"listenerId":"lsn_3f0b8c1e-7a4d-4e52-9b6a-0c2d1e8f9a47","events":["message.delivered","message.failed"],"expiresAt":"2026-11-19T13:05:00.000Z"}
: ping
event: event
id: evt_c7e9g2i4k6m8o1q3s5u7w9y2
data: {"id":"evt_c7e9g2i4k6m8o1q3s5u7w9y2","type":"message.delivered","createdAt":"2026-11-19T13:01:12.000Z","orgId":"org_n5q8t1w4z7c0f3i6l9o2r5u8","data":{…}}
event: rotate
data: {}
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.