Receive inbound SMS with a webhook
Outbound is easy; the real power is reacting to what customers send back. This guide shows how incoming texts reach your own server as HMAC-signed webhooks, how to verify them, and how to turn each one into action.
How inbound delivery works
When someone texts the number on your paired phone, the app captures the message and the service forwards it to an HTTPS endpoint you control. The delivery is signed with HMAC-SHA256 using a secret only you and the gateway share, so you can prove the request is genuine before acting on it. Nothing is polled and nothing waits in a mailbox — your code is called the moment a reply arrives.
Step 1 — Register your endpoint
Choose a publicly reachable HTTPS URL in your application — for example /hooks/sms — and register it as your inbound webhook. At registration you receive a signing secret (a whsec_ value). Store it securely; it never travels in the request body. You can register one endpoint for everything or different endpoints per use case.
Step 2 — Verify the signature
Every delivery carries a signature header. Before trusting a payload, read the raw request body exactly as received, compute an HMAC-SHA256 over it using your secret, and compare the hex digest to the header value with a constant-time comparison. If they do not match, reject the request with a 401. Verifying on the raw bytes — not a re-serialized object — is essential, because any reformatting changes the hash. The exact header name and field names are listed in the webhooks reference.
Step 3 — Acknowledge quickly
Return a 2xx as soon as you have stored the message. Do the slow work — CRM lookups, ticket creation, notifications — asynchronously, after you have responded. If your endpoint is slow or returns an error, the delivery is retried, so make your handler idempotent: key on the message ID and ignore duplicates.
Step 4 — Act on the message
With a verified payload you have the sender's number, the text, and a timestamp. From here you can attach the reply to a contact in your CRM, open or update a helpdesk ticket, trigger a no-code auto-reply, or branch on keywords like "STOP" to honour opt-outs. Two-way conversations now run entirely through your own systems.
Scan to install
Start receiving replies
Install the Android app, pair your phone, register an endpoint, and catch your first inbound text.
Related
Webhooks reference · No-code auto-reply rules · Route SMS into your helpdesk · REST API reference