Messaging

SMS Webhook

An SMS Webhook is an HTTPS POST that fires from a virtual-number provider to a customer-controlled URL whenever an inbound SMS arrives. The payload carries sender, recipient DID, body, timestamp, MMS attachments, and a HMAC-SHA256 signature so the receiver can verify authenticity.

How it works

An inbound SMS arrives at the terminating carrier and is decoded by the messaging service. Instead of (or in addition to) email forwarding, the service issues an HTTPS POST to the URL configured for the receiving DID. The body is a JSON document; a per-account secret signs the raw bytes via HMAC-SHA256, and the signature appears in an X-DIDHub-Signature header.

The receiving server verifies the signature using a constant-time comparison, parses the JSON, and processes the SMS — typically by storing it, replying via the outbound SMS API, posting to Slack/Teams, creating a ticket in Zendesk/Salesforce, or routing into an LLM for an AI auto-responder.

Payload shape

{
  "event": "sms.received",
  "id": "msg_a4f9c2b1",
  "timestamp": "2026-05-07T14:32:18Z",
  "to": "+14155550123",
  "from": "+14155554567",
  "country": "US",
  "body": "Hi, can someone call me back?",
  "encoding": "GSM-7",
  "segments": 1,
  "mms": [],
  "meta": { "did_id": "did_3f8c1a2", "trunk_id": "trunk_a4f9" }
}

The id field is stable across retries — use it as the dedupe key in your handler. encoding values are GSM-7, UCS-2, or Latin-1; the body is always UTF-8 regardless.

Security

• HMAC-SHA256 signature. Every webhook is signed with a per-account secret. Verify before trusting any payload — this prevents impersonation by anyone who knows your URL.
• HTTPS only. Plain-HTTP endpoints are refused.
• IP allowlist. Lock your firewall to the published origin range at /.well-known/webhook-origins for defense-in-depth.
• Replay protection. Cache recent id values; ignore duplicates from retries.
• Per-DID secrets. For multi-tenant systems, set per-DID secrets so a leaked secret only affects one tenant.

Retries

The service waits up to 5 seconds for a 2xx response. If the handler times out, returns 5xx, or fails to connect, the request retries with exponential backoff: 0s, 5s, 30s, 2 min, 10 min, 1 hour, then 6-hour intervals up to a 36-hour total. After all retries fail the message is marked delivery_failed and can be manually re-triggered from the dashboard. 4xx responses do not retry — treat them as final.

Best practice: respond 200 immediately and queue the SMS for async processing. A handler that takes 5 seconds to do real work blocks the next inbound from the same trunk — a fast-ACK + worker queue pattern keeps throughput high under load.

When to use it instead of email

SMS-to-Email is the simplest delivery mode — no code required — and is ideal for low-volume manual workflows. SMS-Webhook unlocks programmatic processing: two-way conversations, AI auto-responders, structured CRM integration, custom routing logic, low-latency reply pipelines. The two modes can be combined — every inbound SMS fans out to both your webhook and configured email recipients in parallel.

For a step-by-step walkthrough, see the tutorial or the full landing page with code samples in Node, Python, and Go.

Related terms

Related glossary terms

Asterisk (open-source PBX framework)

Asterisk is the original open-source telephony framework, started by Mark Spencer in 1999. It is a Class 5 PBX engine: it terminates SIP/IAX

Read →

Attestation Levels (A, B, C)

Attestation levels are the three trust ratings that an originating carrier assigns to outbound calls under STIR/SHAKEN. They tell the termin

Read →

Auto-Provisioning (zero-touch desk phone setup)

Auto-provisioning is how you deploy 50, 500, or 50,000 desk phones without manually configuring each one. The phone boots, fetches its confi

Read →

BYOC (Bring Your Own Carrier)

BYOC is a deployment model where you use a third-party SaaS platform (Vapi, Retell, Microsoft Teams, Zoom Phone, Twilio Flex) for the call-c

Read →