WhatsApp Webhook Not Receiving Messages? A Debugging Checklist
Any statistics or percentages in this article are general industry figures or illustrations, not QuackAPI measurements or promises. Results depend on your audience, consent and sending patterns. QuackAPI connects to WhatsApp as a linked device (an unofficial method), so read our risk and acceptable use policy before sending.
What QuackAPI sends
Each device has its own webhook URL. QuackAPI sends an HTTP POST with a JSON body for four events: message.received, message.sent, message.failed and message.unknown. Incoming media arrives as text such as "[Image]" followed by the caption.
1. Is the URL set on the right device?
Webhooks are configured per device, not per account. If you have several devices, check the one that actually receives the messages. Make sure the URL has no typo and uses https.
2. Is the device connected?
A disconnected device receives nothing. Confirm the status is connected before debugging anything else.
3. Is your URL reachable from the internet?
localhost and private addresses cannot be reached from QuackAPI's servers. While developing, expose your machine with a tunnelling tool and use its public https URL. Check firewalls and that the path is not behind a login.
4. Do you answer with a 2xx quickly?
Respond with a 2xx status straight away and do slow work afterwards. Redirects, errors or long processing look like failures from the sender's side.
app.post("/whatsapp-webhook", express.json(), (req, res) => {
res.sendStatus(200); // answer first
queue.add(req.body); // process later
});5. Read the webhook log
The device page lists every webhook attempt and what your server answered. If attempts appear with errors, the problem is on your side. If nothing appears, the event was not generated or the URL is not saved.
6. Parse the payload you actually get
For message.received the fields are event, deviceId, from, content, timestamp and messageId. For message.sent they are event, messageId, to, deviceId and status. For message.failed and message.unknown there is an error field. Log the raw body once to confirm.
{
"event": "message.received",
"deviceId": 1,
"from": "923001234567",
"content": "Hi",
"timestamp": 1700000000,
"messageId": "ABC123"
}7. Plan for duplicates and spoofing
Use messageId to make processing idempotent. Webhooks are not signed today, so keep the URL secret and unguessable and validate the fields you depend on. Do not trust a webhook as proof of identity.