To keep an SMS webhook handler working when the provider changes it, store the raw payload, read only the fields you need, ignore everything else, and return a 2xx for event types you don't recognize. This is the tolerant reader pattern, and it turns most provider changes into non-events.
We make Ready, so the examples refer to Ready webhooks without naming event types or fields, since the webhook docs are the source for those. The pattern works for any provider.
The failure it prevents
A strict handler validates the body against a schema that forbids unknown fields. It works for a year. Then the provider adds a field, every webhook fails validation, your endpoint returns a 400, and the provider retries and eventually gives up. You find out when customers ask why replies stopped appearing. The change was harmless, and your code made it an outage.
Four rules
| Rule | Why |
|---|---|
| Store the raw body first | You can replay it after a fix. See dead-letter replay |
| Read only what you use | Extra fields can't break what you don't touch |
| Unknown event type: log and return 2xx | A new event isn't an error. A 4xx makes the provider retry for nothing |
| Missing field you need: park, don't crash | A real gap needs a person, and shouldn't drop the other events |
A handler that follows them
import { z } from 'zod';
const Envelope = z.object({
type: z.string(),
}).passthrough(); // keep unknown fields
export async function handle(rawBody: string, headers: Headers) {
verifySignature(rawBody, headers); // before anything else
await db.webhookRaw.insert({ body: rawBody, receivedAt: new Date() });
const parsed = Envelope.safeParse(JSON.parse(rawBody));
if (!parsed.success) return { status: 202 }; // park, alert, don't 4xx
const handler = handlers[parsed.data.type];
if (!handler) {
log.info('unhandled webhook type', { type: parsed.data.type });
return { status: 200 };
}
await queue.add(parsed.data.type, parsed.data);
return { status: 200 };
} passthrough() keeps unknown fields instead of rejecting them. Verify the signature first, and read it from the raw text, since a re-serialized body won't match. Our signing post explains why. The handler returns fast, and the per-type handler runs from the queue.
Parse per handler, loosely
Inside each handler, validate only the fields it needs, and give optional ones defaults:
const InboundReply = z.object({
from: z.string(),
body: z.string().default(''),
}).passthrough(); A reply with a new extra field still parses. A reply with no from doesn't, and that one goes to the park table with an alert. Check the exact field names in the docs and don't copy these examples.
Order and duplicates
Providers can deliver events twice or out of order, so your handler should be idempotent: key on an event or message ID, and compare timestamps before overwriting status. A "delivered" event that arrives before "sent" mustn't roll a message back. The event ordering post shows how.
Watch for drift
A tolerant reader hides change, which is the point, and also the risk. Add two alerts: a count of unhandled event types, and a count of parked payloads. A new event type showing up in the first is a prompt to read the docs and decide whether you want it. Our observability guide covers alert design.
FAQ
Should I reject payloads that fail validation?
Not with a 4xx. Store them, return a 2xx or 202 and alert. A rejected webhook is a lost event once the provider stops retrying.
How should I test it?
Replay stored real payloads through the handler, add a fake extra field and a fake new event type to the fixtures, and assert both return 2xx.
Can I test webhooks locally?
Yes. See testing SMS webhooks locally.
The short version
Raw body first, loose parsing, 2xx for the unknown and an alert on drift. The webhook docs list the events.
Cost and registration
A segment on the Standard rate is $0.0075 plus a $0.0045 carrier fee, passed through at cost, excluding optional screening. An account can send up to 500 texts a month before it registers for 10DLC, and most approvals take 2 to 7 days. See pricing for the full list.