Status webhook

OTPBay sends a POST to your callback URL when an SMS is sent or fails, when a Telegram code’s delivery status changes, and when a verification finishes. Every channel sends the same body. Respond with any 2xx status within 15 seconds.

WEBHOOK statusUpdate

JSON

verification

{
  "sid": "VE6650c3a1b2c3d4e5f6a7b8c9",
  "channel": "verify",
  "status": "approved",
  "to": "[phone]",
  "cost": "0.04",
  "metadata": {
    "user_id": "usr_1042"
  },
  "error": null,
  "date_created": "2026-09-26T10:15:01.873Z",
  "date_updated": "2026-09-26T10:15:40.530Z"
}

Body

application/json

sid · string · required

sid of the verification (VE…), SMS (SM…) or Telegram code (TG…).

Example:

"VE6650c3a1b2c3d4e5f6a7b8c9"

channel · enum<string> · required

Which API the event is about.

Available options: verify, sms, telegram

status · string · required

New status. verify: approved, expired, failed. sms: sent, failed. telegram: sent, delivered, read, expired, revoked, failed.

Example:

"approved"

to · string · required

Destination phone number in international format. OTPBay normalizes it to E.164, so [phone] becomes [phone].

Example:

"[phone]"

cost · string · required

What the object costs at the time of the event, after refunds.

Pattern: ^\d+\.\d{2}$

Example:

"0.02"

metadata · object · required

Your own key-value data, returned in responses and webhooks. At most 32 keys of 1–64 characters. Values are strings (up to 512 characters), numbers or booleans.

Hide child attributes

metadata. {key} · string number boolean

Maximum string length: 512

Example:

{ "user_id": "usr_1042" }

error · string | null · required

Error message when the status is a failure, otherwise null.

date_created · string<date-time> · required

date_updated · string<date-time> · required

Response

200

Return any 2xx status to acknowledge the event. The response body is ignored.