Skip to content
Developers

Webhooks

Webhooks

Be told when a message is sent, delivered or fails.

Webhooks tell your system the moment something happens, so you don’t have to ask. Add an endpoint under Webhooks, choose its events, and Falconzo sends each one to it as a POST with a JSON body.

Events

sms.sentevent
An SMS was handed to the mobile network
sms.deliveredevent
An SMS reached the phone
sms.failedevent
An SMS couldn't be delivered

sms.failed covers both FAILED and EXPIRED; read status to tell them apart. The webhook.test event is only sent when you press “Send test event”.

What you receive

Request to your endpoint
POST /falconzo-events HTTP/1.1
Content-Type: application/json
Falconzo-Event: sms.delivered
Falconzo-Delivery: cmx9del7ivr
Falconzo-Signature: t=1762596904,v1=5f2b7c...

{
  "id": "evt_8c1f4e2a9b7d4c0e8f1a2b3c4d5e6f70",
  "type": "sms.delivered",
  "createdAt": "2026-11-08T10:15:04.000Z",
  "livemode": true,
  "data": {
    "message": {
      "id": "cmx1abc2def3",
      "to": "94771234567",
      "from": "ABCSHOP",
      "status": "DELIVERED",
      "clientReference": "1042",
      "deliveredAt": "2026-11-08T10:15:04.000Z"
    }
  }
}
idstring
The event’s id. The same event can arrive more than once; use this to ignore repeats.
typestring
The event name, also in the Falconzo-Event header.
createdAtstring
When it happened (ISO 8601).
livemodeboolean
false when a test key caused it.
data.messageobject
The message, with the same fields as Get an SMS.

Answering

  • Answer with any 2xx status within 10 seconds. The body is ignored.
  • Do slow work after answering (put the event on your own queue first).
  • Redirects are not followed: point the endpoint at the final address.
  • Outside local development the address must start with https://, because events hold phone numbers and message text.

Retries

If your endpoint doesn’t answer with 2xx, Falconzo tries again with growing gaps for about a day. Every attempt is listed on the endpoint’s page, where you can also resend one. An endpoint that fails 50 deliveries in a row is switched off; switch it back on once it is fixed.

Events can arrive out of order (a retried sms.sent after sms.delivered). Use status and the timestamps in data.message, not the order of arrival.

Check the signature

Anyone can POST to a public address. Check the Falconzo-Signature header on every event before trusting it; Verifying webhooks shows how.