WhatsApp delivery statuses and webhooks, explained

Sending a WhatsApp message is only half the story. The other half — did it arrive? was it read? did it fail? — comes back asynchronously through webhooks. Here's how WhatsApp's status model works and how to consume it without shooting yourself in the foot.

The status ladder

• accepted — WhatsApp took your send request (the 200 you get back).
• sent — it left WhatsApp toward the recipient.
• delivered — it reached the recipient's device.
• read — they opened it (if they have read receipts on).
• failed — it couldn't be delivered, with an error reason.

Statuses only move forward — a message that's read shouldn't drop back to delivered. And a 200 at send time is not “delivered”; treating it that way is a common mistake.

How webhooks deliver this

Meta POSTs events to a webhook URL you register: inbound messages from customers, and status updates for messages you sent. Two things you must get right:

• Verify the signature. Each webhook is signed (HMAC) with your app secret. Verify it over the raw body before trusting anything — otherwise anyone can POST you fake events.
• Deduplicate. Meta retries webhooks, so you'll see the same event more than once. Key on the message id and process each once.

Inbound messages matter too

Webhooks also carry the customer's replies — and each inbound message resets their 24-hour window. So your webhook handler isn't just for analytics; it's what tells you the window is open again.

Ack fast, work later

Webhook handlers should acknowledge quickly (a fast 200) and defer heavy work, or Meta will consider the delivery failed and retry — amplifying load. Persist and return; process asynchronously.

What walpio does with all this

walpio runs the webhook pipeline for you: per-tenant signature verification, deduplication, a full status timeline per message, and inbound handling that keeps your window state correct. You just read the results — in the API or the dashboard — instead of building and hardening a receiver yourself.