Webhook: definition and how it works
Published and updated
A webhook is an HTTP request a service sends to a URL you own when something happens, so your code learns about an inbound SMS or a delivery event the moment it occurs instead of polling for it.
How it works
Polling asks a question over and over: has anything arrived yet? A webhook inverts that. You register a URL with the service, and the service POSTs to it when an event happens, with the event's data in the body. Your endpoint returns a 2xx status to acknowledge it. For SMS the events are the ones you would otherwise poll for: a message was received on your number, a message you sent was handed to the carrier, was delivered, or failed.
Three habits make webhooks reliable. Verify the request: a good provider signs each delivery with a secret you set, typically an HMAC over the body sent in a header, so your endpoint can reject anything that did not come from the provider. Deduplicate: deliveries are retried when your endpoint is slow or returns an error, so every payload carries an idempotency key and you should store the ones you have processed. Return quickly: do the real work in a queue or background job and answer 200 within a second or two, because a slow endpoint gets retried and eventually paused.
The endpoint must be reachable from the internet over HTTPS. In development that means a tunnel or a staging deployment; providers refuse private and loopback addresses.
Webhooks and polling are complements, not rivals. Webhooks give latency, polling with a cursor gives a guaranteed catch-up after an outage on your side.
How this applies with textbee
textbee webhooks deliver MESSAGE_RECEIVED, MESSAGE_SENT, MESSAGE_DELIVERED and MESSAGE_FAILED as a flat JSON body with an idempotencyKey, signed with HMAC-SHA256 over the body in the X-Signature header using the secret you set per subscription. Failed deliveries are retried, and you can register more than one endpoint on an account.
Related terms
- Delivery receipt: A delivery receipt is the network's report that an SMS reached the recipient's handset, or failed to, surfaced by a gateway as a status on the message.
- Two-way SMS: Two-way SMS is messaging where recipients can reply to the number that texted them and the sender's software receives and acts on those replies.
- SMS API: An SMS API is a programmatic interface, almost always HTTP, that lets software send text messages, read the ones that arrive, and check what happened to each one.
Frequently asked questions
What happens if my webhook endpoint is down?
The provider retries the delivery on a schedule, reusing the same idempotency key. Once your endpoint is back you process the backlog, and a cursor-based poll of the messages endpoint fills any gap.