Skip to content
Meta Business PartnerDeveloper how-to

How to receive WhatsApp messages and delivery updates with webhooks

Every message a customer sends you, and everything that happens to the messages you send, reaches your system as a webhook: an HTTPS POST from InfiQ to an endpoint you register. This guide sets up that endpoint, shows the payloads for an inbound message and a failed delivery, and covers retries and duplicates.

HTTPS POST with a JSON envelope
Transport
X-InfiQ-Signature, HMAC-SHA256
Signature
message.received
Inbound event
message.sent, .delivered, .read, .failed
Status events
The event id (X-InfiQ-Event-Id)
Dedupe on
Exponential backoff for 24 hours
Retries

In short

Register an HTTPS endpoint in the InfiQ dashboard and subscribe to the events you need, such as message.received, message.delivered, message.read and message.failed. Each delivery is a JSON envelope with an id, a type and the event in data, signed in the X-InfiQ-Signature header. Verify the signature, dedupe on the event id, queue the work and answer with a 2xx quickly.

Register your endpoint

In the dashboard, add your endpoint's HTTPS URL, choose the events and copy the endpoint secret, which is shown only once (whs_live_…). There is no Meta verify-token handshake to build: InfiQ receives Meta's webhooks for your number and posts its own signed events to you. InfiQ catalogues 27 event types across messages, campaigns, contacts, templates, API keys, your WhatsApp account and the system; most integrations start with the message events.

Write a small receiver

Read the raw body, check the signature, skip events you've already handled, hand the rest to a queue and answer with a 2xx. The signature check is a function call here; the signature guide shows it in full.

import express from "express";
import { verifyInfiqSignature } from "./verify.js";
const app = express();
const seen = new Set(); // use your database or Redis in production
// express.raw keeps the exact bytes the signature covers.
app.post("/webhooks/infiq", express.raw({ type: "application/json" }), (req, res) => {
if (!verifyInfiqSignature(req.get("X-InfiQ-Signature"), req.body)) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString("utf8"));
if (!seen.has(event.id)) {
seen.add(event.id);
queueEvent(event); // your job queue does the real work
}
res.sendStatus(200);
});
app.listen(3000);

Handle an inbound message

message.received carries what the customer sent. In it, from is the customer and to is your business number, the reverse of the status events. contentType is Meta's raw message type (text, image, audio, button, reaction and more), so don't fail on a value you don't recognise; content.type is InfiQ's normalised shape, and media messages include a mediaUrl you can download. A reply within 24 hours of this message can be free-form.

{
"id": "01JABCDEF0123456789ABCDEFG",
"type": "message.received",
"apiVersion": "2026-04",
"createdAt": "2026-07-30T10:15:42.113Z",
"livemode": true,
"data": {
"message": {
"id": "b3d1c0a2-1f4e-4a77-9c2b-8e2f7a1d6b90",
"to": "+919812345670",
"from": "+919876543210",
"senderName": "Aditya Rao",
"channel": "whatsapp",
"direction": "inbound",
"contentType": "text",
"wamid": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgUM0E1RjYyN0RCM0ExQjJDNEQ1RTYA",
"content": {
"type": "text",
"text": "Hi, is my order shipped yet?"
}
}
},
"_meta": {
"deliveryId": "4d6c8a02-9e1f-4b7a-8c33-2f0a9b1c7d55",
"attempt": 1
}
}

Trimmed: real deliveries also carry tenantId, correlation and the raw Meta message under content.raw.

Track delivery statuses

Every message you send produces status events that carry its wamid:

  • message.sent: Meta handed the message to WhatsApp.
  • message.delivered: it reached the customer's phone.
  • message.read: the customer opened it. This arrives only if they allow read receipts, so a missing read event means unknown, not unread.
  • message.failed: it couldn't be delivered. This event has two shapes. A delivery-time failure carries data.message and data.error with metaErrorCode; a send-time failure carries a flat data object with meta_error and failure_reason. Branch on whether data.message is present.
{
"id": "01JQ8ZK5P1AS4X6Y8Z0A2B4C6D",
"type": "message.failed",
"apiVersion": "2026-04",
"createdAt": "2026-07-30T09:15:10.004Z",
"livemode": true,
"data": {
"message": {
"id": "5f2e9a10-7c31-4b8e-9d02-6a1b2c3d4e5f",
"to": "919100000001",
"channel": "whatsapp",
"direction": "outbound",
"wamid": "wamid.HBgMOTE5MTAwMDAwMDAxFQIAERg"
},
"error": {
"code": "131026",
"message": "Message undeliverable",
"metaErrorCode": 131026
}
}
}

Retries and duplicates

If your endpoint doesn't answer with a 2xx, InfiQ retries with exponential backoff for 24 hours. A retry carries the same event id (also sent as the X-InfiQ-Event-Id header), so dedupe on the id, not on the delivery. The attempt number is in the X-InfiQ-Attempt header; _meta.attempt in the body always says 1. Don't rely on arrival order either: store the furthest status per wamid, so a late delivered event can't overwrite a read you already recorded.

Test without a live customer

POST an event type to /v1/webhooks/test and InfiQ sends a sample event, signed like production traffic, to your registered endpoints:

curl -X POST https://api.infiq.in/v1/webhooks/test \
-H "X-INFIQ-API-KEY: $INFIQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"event": "message.received"}'
# 202 Accepted
# {"id": "evt_test_1a2b", "status": "queued"}

Works with sandbox (isk_test_…) keys. The event is signed exactly like real traffic.

Get your InfiQ API key

Frequently asked questions

Can I receive WhatsApp messages through the API?+
Yes, as webhooks. Register an endpoint and subscribe to message.received; each customer message arrives as a signed POST with the sender, the content and, for media, a download URL.
Why do I receive the same webhook more than once?+
Deliveries are retried until your endpoint answers with a 2xx, so a slow or failed response leads to a retry. Retries keep the same event id: store the ids you've processed and skip repeats.
Do I need to handle Meta's hub.challenge verification?+
Not with InfiQ. InfiQ is subscribed to Meta's webhooks for your number and forwards the events in its own signed format, so you verify InfiQ's X-InfiQ-Signature header instead.
How do I know if a WhatsApp message was read?+
Subscribe to message.read. It arrives with the wamid and a readAt time when the customer opens the message, but only if they have read receipts turned on.