How do WhatsApp webhooks work?

What events you actually receive

Nearly everything useful arrives under the single messages field, but the payload varies by what happened. Inbound customer messages come through as message objects (text, image, document, audio, location, interactive button and list replies, and more), each stamped with the sender's wa_id and a timestamp. Outbound message lifecycle updates arrive as statuses objects that progress through sent, delivered, read, and failed — this is how you build accurate delivery dashboards and trigger retries. Beyond messaging, account-level fields tell you when a template is approved or rejected, when your messaging limit tier changes, when your phone number's quality rating shifts to yellow or red, or when account review status updates. Subscribe deliberately: fewer fields means cleaner payloads and less noise to filter.

• Inbound messages: text, media, location, contacts, and interactive replies
• Statuses: sent, delivered, read, failed — plus pricing category metadata
• message_template_status_update: template approved, rejected, or paused
• phone_number_quality_update and account_update for health and limit changes

Reading a status payload — and what the pricing fields mean

Each status event includes a pricing block, and this is where accuracy matters. Since Meta retired per-conversation billing on 1 July 2025, WhatsApp charges per delivered message by category — marketing, utility, or authentication. Your webhook's status payload surfaces that category so you can attribute cost to the right message type in your own reporting, rather than guessing. The 24-hour customer service window still exists, but it is now a free service window that lets you reply to a user without a template — it is no longer a billing unit. Treating those status fields correctly means your internal analytics match your actual invoice: count delivered messages, group by category, and you have a live cost picture. InfiQ's platform reconciles these events for you so your dashboard reflects Meta's live rate card without you writing that logic from scratch.

Securing and scaling your endpoint

Because a webhook URL is publicly reachable, you must prove each request genuinely came from Meta. Every POST carries an X-Hub-Signature-256 header — an HMAC-SHA256 of the raw request body computed with your app secret. Recompute it on your side and reject any request whose signature doesn't match, which blocks spoofed or replayed payloads. Two more practices keep production stable: acknowledge fast and process later, and handle duplicates. Meta expects a 200 within seconds, so push the payload onto a queue and return immediately rather than doing database writes or bot logic inside the request. Meta also retries on non-200 responses and can occasionally deliver the same event twice, so make your handler idempotent — key off the message or status ID so a repeat delivery is a no-op.

• Validate X-Hub-Signature-256 against your app secret on every request
• Return HTTP 200 within seconds; queue the payload for async processing
• Deduplicate on message/status IDs to stay idempotent under retries
• Log raw payloads so you can replay events during debugging

How InfiQ handles webhooks for you

Wiring, verifying, signing, deduplicating, and scaling a webhook consumer is real engineering work — and a single missed 200 can cause Meta to back off delivery. InfiQ, an official Meta Business Partner, manages the ingestion layer so your team consumes clean, normalised events instead of raw Cloud API plumbing. Inbound messages route into shared inboxes and bot flows, delivery statuses populate live analytics, and template state changes surface automatically. Critically, you keep full ownership of your WhatsApp Business Account and BSUID, so you're never locked in — and you can still connect your own systems via forwarded webhooks or APIs when you want custom automation. You get the real-time power of webhooks with transparent ₹ pricing, without maintaining the infrastructure yourself.