Key Takeaways
- Android SMS gateway webhooks are HTTPS callbacks for message.delivered, message.failed, message.received, and USSD responses — confirm the live list in OpenAPI.
- Verify X-SmsGateway-Signature (HMAC) and dedupe X-SmsGateway-Event-Id.
- Register with POST /webhooks. Do not invent a query-string secret.
- The radio still needs a phone and operator credit. Webhooks do not send SMS.
- Service pricing is based on device count and total SMS sent through the gateway. You need a working Android phone with a SIM and SMS credit from your mobile operator. Operator message costs are yours—we do not sell carrier SMS balance.
An Android SMS gateway webhooks overview is the control-plane story: the phone sent (or received) something; your server needs to know without sitting on GET. Events are signed. Retries happen. Your handler must not send a second OTP because it saw the same event twice.
Service pricing is based on device count and total SMS sent through the gateway. Product: SMS webhooks. Schema: API docs.
If the handler cannot prove the HMAC, it is not a webhook. It is an open POST on the internet.
Why webhooks beat polling
DLR latency, inbound STOP, USSD menus — polling every second burns your workers and still misses bursts. Push, then GET if you need a reconcile. Delivery reports.
Event table
| Event (typical) | Use | Trap |
|---|---|---|
| message.delivered / failed | OTP SLO, tickets | Treating failed as “user declined” |
| message.received | STOP, YES, support | No owner; auto-reply loops |
| ussd.response | Balance / menus | Assuming it is SMS DLR |
Live event names: OpenAPI webhooks key. Illustrative delivered payload:
{
"id": "evt_01K2F8QW3N4RXB7M",
"type": "message.delivered",
"createdAt": "2026-08-12T14:04:09Z",
"apiVersion": "2026-08-12",
"data": {
"message": {
"id": 41823,
"number": "+14155552671",
"text": "Your verification code is 481920",
"status": "Delivered",
"campaignId": 17,
"deviceId": 3,
"metadata": { "orderId": "1234" },
"sentAt": "2026-08-12T14:04:02Z",
"deliveredAt": "2026-08-12T14:04:09Z"
}
}
}Signature and timestamp
X-SmsGateway-Signature = v1= hex HMAC-SHA256 of timestamp.body with the signing secret. Timestamp header is unix seconds. Dedupe on X-SmsGateway-Event-Id. Docs win if this comment ever drifts.
POST /webhooks
Register HTTPS URLs you control. Localhost is not reachable from the cloud relay. You need a working Android phone with a SIM and SMS credit from your mobile operator. Operator message costs are yours—we do not sell carrier SMS balance.
Your endpoint must be idempotent
We (and networks) retry. Same event id → no second SMS. Client retry backoff is a different layer.
Checklist
- HMAC verified.
- Event-id store.
- TLS URL, not HTTP-open.
- OTP not sent from the webhook handler without a challenge row.
- Fields confirmed in docs.
Next steps
Pair a phone via downloads, register a webhook, send a canary, and prove the signature check fails when you tamper the body.
Related product pages
Jump to the live product docs for this topic—not another long-form article.
- SMS webhook integrationInbound and status events
- SMS API documentationLive endpoint reference
- device and SMS volume pricingPlans and allowances
- Android SMS gateway product guideDefinition, product, and how to buy
