OTP

Events and webhooks

When a code's status or channel changes, we POST it to your server, signed with your webhook secret.

Where events go#

To the request's callback_url, if it had one.
Otherwise to each of your webhooks for the code's channel.
With no webhooks at all, to your account's callback URL on Webhooks.

The request#

Example event

POST /hooks/otp HTTP/1.1
Content-Type: application/json
User-Agent: smsgw-webhooks/1
X-Smsgw-Timestamp: 1793351709
X-Smsgw-Signature: v1=9e36a876201b9e7557c809ff81c89c5570deae01cea979cdcc5ab96715ac2ca3

{
  "event_id": "evt_5c0e8f3a9b7d4e21a6f0c3d8",
  "type": "verification.status",
  "verification_id": "7c1e0b52-9d2f-7a41-8e33-52d0f1c7ab90",
  "status": "delivered",
  "channel": "telegram",
  "to": "+447700900123",
  "payload": "signup-4821",
  "error": null,
  "created_at": "2026-11-02T09:15:02.123456Z",
  "occurred_at": "2026-11-02T09:15:04.5Z"
}

event_idstring

Unique to the event, and the same on every retry of it.

typestring

Always verification.status. Your account's callback URL also gets message.status, so look at this first.

verification_idstring

Its id.

statusstring

Its new status.

channelstring

The channel carrying the code: when it falls back you get sent again, on sms.

tostring

The number.

payloadstring

Your own value, if you sent one.

errorstring

Why it failed, if it did.

created_atstring

When it was started.

occurred_atstring

When this event was made.

Changes close together read as one event with the latest status, so don't count on seeing each step. Signatures, retries and duplicates work as for delivery webhooks.

Manage webhooks#

Also on the OTP page of the console. An account can have up to 10.

GEThttps://api.siellabs.com/v1/webhooks

POSThttps://api.siellabs.com/v1/webhooks

GEThttps://api.siellabs.com/v1/webhooks/{id}

PUThttps://api.siellabs.com/v1/webhooks/{id}

DELETEhttps://api.siellabs.com/v1/webhooks/{id}

Body#

urlstringRequired

A public http(s) URL.

namestringOptional

Up to 80 characters, for you.

channelsstring[]Optional

Only these channels' events: telegram, sms. Empty: all of them.

201 Created

{
  "id": "0193f2a4-6f1e-7c3a-9d10-2b7e4a1c8f55",
  "name": "Sign-up service",
  "url": "https://example.com/hooks/otp",
  "channels": ["sms"],
  "created_at": "2026-11-02T09:15:02Z",
  "updated_at": "2026-11-02T09:15:02Z"
}