How to set up webhooks on the WhatsApp Business API
Webhooks are how the WhatsApp Business API pushes real-time events to your systems: inbound customer messages, message status updates (sent, delivered, read, failed), template quality changes and account alerts. Instead of polling for data, you register one HTTPS endpoint and Meta posts a JSON payload the moment something happens. This tutorial walks through configuring webhooks end to end with InfiQ, from choosing where events should land to verifying the handshake, subscribing to the right fields, and confirming a live message reaches your endpoint. If you use InfiQ's no-code inbox and automation, most of this is handled for you; if you're wiring events into your own CRM, helpdesk or backend, follow every step below.
What you'll do
Point the WhatsApp Business API at one HTTPS endpoint, answer Meta's verification handshake with your verify token, subscribe to the messages field, then send a test message and confirm the payload arrives. InfiQ manages the underlying Meta configuration so you can route events to its inbox, your CRM, or a custom URL.Step 1 — Decide where your events should land
Before touching any configuration, choose the destination for your webhook traffic. There are two clean paths, and picking the right one first saves rework. If you want conversations, chatbots and broadcast status all managed for you, route everything into InfiQ's inbox and automation layer — no endpoint to host, no code to maintain. If you need events inside your own stack, you'll host a public HTTPS endpoint that receives Meta's POST requests. Many businesses do both: InfiQ runs live agent conversations while a copy of message and status events also flows to a backend for analytics or CRM sync.
- No-code route: use InfiQ's inbox — InfiQ owns the Meta webhook subscription and surfaces events as conversations and automation triggers.
- Custom route: prepare a public HTTPS URL (valid TLS certificate, reachable from the internet, not localhost).
- Hybrid route: keep InfiQ for agents and automations, and forward a copy of events to your own endpoint — ask InfiQ support to set the routing.
- Confirm your WhatsApp Business API account is active and your number is verified with InfiQ before you begin.
Step 2 — Configure the endpoint and pass the verification handshake
Meta will not send you a single event until it confirms your endpoint is real and under your control. This is a one-time handshake. When you register the callback URL, Meta sends a GET request carrying three query parameters, and your server must echo one of them back verbatim. If the challenge isn't returned exactly, the subscription fails and no events flow. Choose a verify token that is a long, random secret — treat it like a password and keep it out of source control and client-side code.
- Set your callback URL to your HTTPS endpoint (for a custom setup) — InfiQ pre-fills this when you use its managed inbox.
- Meta sends GET params: hub.mode, hub.verify_token and hub.challenge.
- Your server checks that hub.verify_token matches the secret you configured, then responds with the raw hub.challenge value and HTTP 200.
- A mismatched or missing challenge response is the number-one reason a subscription silently fails — log the incoming request while debugging.
Step 3 — Subscribe to the right webhook fields
The WhatsApp Business API can emit several event types, but you should subscribe only to what you'll act on — extra subscriptions just create noise your handler has to discard. The essential field is 'messages', which is deceptively broad: it delivers both inbound customer messages and outbound delivery status (sent, delivered, read, failed) in the same stream. Those 'delivered' events map directly to what WhatsApp bills you, since charges accrue per delivered message by category (marketing, utility or authentication). If you manage templates or sender health in code, add the template-status and quality-alert fields so approvals, rejections and quality-rating changes reach you automatically.
- messages — inbound texts, media and interactive replies, plus outbound status updates. Subscribe to this first.
- message_template_status_update — template approvals and rejections.
- account quality and phone-number quality alerts — early warning before rate limits or restrictions hit.
- Skip fields your application ignores; every subscribed field arrives at the same endpoint and must be routed by payload type.
Step 4 — Secure and acknowledge every payload correctly
A public webhook endpoint is a public attack surface, so validate before you trust. Each POST from Meta carries an HMAC SHA-256 signature computed over the raw request body using your app secret; recompute it on your side and reject any request whose signature doesn't match. Equally important is how fast you reply: Meta expects an HTTP 200 quickly, and if your handler is slow or errors out, Meta assumes failure and retries — which is why the same event can arrive several times. The fix is to acknowledge immediately and process asynchronously, and to make your logic idempotent by de-duplicating on the message ID.
- Validate the X-Hub-Signature-256 header against an HMAC of the raw body before parsing.
- Respond 200 within a couple of seconds; queue the payload and do heavy work off the request thread.
- De-duplicate on the unique message ID so retries never double-process an order, ticket or reply.
- Log rejected and unrecognised payloads so you can spot spoofing attempts and new event shapes.
Step 5 — Test end to end, then go live and monitor
Never assume the pipe works until you've watched a real event travel through it. Send a message to your WhatsApp number from your own phone and confirm the inbound payload reaches your endpoint or appears in the InfiQ inbox. Then send an outbound template to yourself and watch the status stream move from sent to delivered to read. Only after both directions are verified should you enable webhooks for real customer traffic. Once live, monitoring is not optional: delivery failures, quality-rating drops and endpoint downtime all show up in the event stream first, and catching them early protects your sender reputation and your send limits.
- Inbound test: message your number from your own phone; confirm the JSON arrives or the conversation opens in InfiQ.
- Outbound test: send a template to yourself and trace the sent → delivered → read status events.
- Watch for failed statuses — they signal opt-in, template-category or number-warming problems, not endpoint bugs.
- After go-live, monitor delivery and read rates and quality alerts; InfiQ's dashboard surfaces these alongside transparent ₹ pricing (ex-GST).