A webhook is an HTTPS request the gateway sends to your endpoint when something happens (a message is delivered or fails, a reply arrives, the balance runs low), so you do not have to poll for status.
Polling asks the API, again and again, whether anything has changed; most answers are "not yet", each one costs a request against the rate limit, and the news arrives late. A webhook reverses the direction: you register an HTTPS endpoint, and the gateway POSTs an event to it when something happens. Each event carries an id, a type, a timestamp and the data, and it is signed so that you can check where it came from.
Delivery is at-least-once. When your endpoint is slow or down, the event is retried, and a retry after a slow success means the same event can arrive twice; nor is order guaranteed. A handler built for production expects all of that:
- Verify the signature on the raw body and reject stale timestamps.
- Store the event and answer 2xx at once; do the work from a queue.
- Deduplicate on the event id.
- Apply status changes forward only, so that a late "sent" never overwrites "delivered".
Example
A hypothetical deploy takes an endpoint offline for twenty minutes. The events generated in that window fail, are retried on a growing schedule and land once the endpoint is back. The handler checks each event id, applies the ones it has not seen, and nothing is lost.
Common mistakes
- Doing slow work before responding, which causes timeouts, retries and duplicates.
- Parsing the JSON before verifying the signature.
- Assuming events arrive in order, or only once.
At SMSMeteor: the documented events are message.sent, message.delivered, message.failed, message.expired and message.rejected for traffic; campaign.started, campaign.paused and campaign.completed for campaigns; and balance.low and balance.credited for the account, with any subset per endpoint. Inbound messages for rented numbers with inbound also arrive by webhook. Every event is signed with HMAC-SHA256 in X-Meteor-Signature, with X-Meteor-Timestamp alongside. Your endpoint must answer 2xx within 5 seconds; otherwise delivery is retried, six attempts over 24 hours (immediately, then +1 min, +5 min, +30 min, +2 h and +12 h), after which the event is marked undelivered. Undelivered events stay listed per endpoint in the panel for 30 days and can be replayed one by one or in bulk, keeping their original event id. Test keys fire webhooks signed like live ones. See the webhooks documentation.
