Guide

Complete Guide to WhatsApp Webhooks

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.

February 5, 20266 min read

What Are Webhooks?

Webhooks are HTTP callbacks that send real-time data to your application when specific events occur. Instead of continuously polling an API for new messages, webhooks push data to your server the moment a new message arrives.

In the context of WhatsApp API, webhooks notify your application whenever a connected device receives an incoming message. This enables you to build real-time chatbots, support systems, and automated workflows.

Setting Up Your Webhook Endpoint

Your webhook endpoint needs to be a publicly accessible HTTPS URL that can receive POST requests. The endpoint should respond with a 200 status code quickly to acknowledge receipt of the webhook payload.

Here is a basic Express.js endpoint that receives incoming WhatsApp messages:

javascript
const express = require("express");
const app = express();

app.use(express.json());

app.post("/webhook/whatsapp", (req, res) => {
  const { event, deviceId, from, message } = req.body;
  
  console.log(`New message from ${from} on device ${deviceId}`);
  console.log(`Type: ${message.type}, Content: ${message.content}`);
  
  // Process the message (save to DB, trigger response, etc.)
  
  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log("Webhook server running on port 3000"));

Handling Incoming Messages

The webhook payload contains the event type, device ID, sender phone number, and message details including type, content, timestamp, and a unique message ID. You should validate and parse this data before processing.

Different message types require different handling. Text messages contain plain string content, while media messages include URLs to the media files. Build a message handler that routes each type appropriately.

javascript
function handleMessage(payload) {
  const { event, from, message } = payload;
  
  switch (message.type) {
    case "text":
      handleTextMessage(from, message.content);
      break;
    case "image":
      handleImageMessage(from, message.content);
      break;
    default:
      console.log(`Unhandled message type: ${message.type}`);
  }
}

function handleTextMessage(from, content) {
  // Auto-reply, save to database, forward to support agent
  if (content.toLowerCase().includes("help")) {
    sendAutoReply(from, "How can we assist you today?");
  }
}

Security Best Practices

Always use HTTPS for your webhook endpoint to encrypt data in transit. Validate the incoming request to ensure it originates from QuackAPI by checking request headers or implementing a shared secret.

Rate-limit your webhook endpoint to prevent abuse. Implement request validation to reject malformed payloads. Store webhook data in a queue for async processing to avoid blocking the response and causing timeout issues.

javascript
// Validate webhook requests
app.post("/webhook/whatsapp", (req, res) => {
  const signature = req.headers["x-webhook-signature"];
  
  if (!isValidSignature(signature, req.body)) {
    return res.status(401).json({ error: "Invalid signature" });
  }
  
  // Queue for async processing
  messageQueue.add(req.body);
  
  // Respond quickly
  res.status(200).json({ received: true });
});

Testing Your Webhooks

During development, use tools like ngrok to expose your local server to the internet. This lets you test webhook delivery without deploying to a production server. Run ngrok http 3000 and use the generated HTTPS URL as your webhook endpoint.

Configure your webhook URL in the QuackAPI device settings. Send a test message to the connected WhatsApp number and verify that your endpoint receives the payload correctly. Check your server logs to confirm the data structure matches your expectations.

Evaluating which provider to use for your webhook integration? See how QuackAPI compares to UltraMsg — including webhook reliability and multi-device support differences.

bash
# Expose local server via ngrok
ngrok http 3000

# Test with curl
curl -X POST http://localhost:3000/webhook/whatsapp \
  -H "Content-Type: application/json" \
  -d '{"event":"message.received","deviceId":1,"from":"923001234567","message":{"type":"text","content":"Test message"}}'

Ready to get started?

Send WhatsApp Messages via API — Free

No Meta Business verification. No credit card. Connect your WhatsApp in under 2 minutes and start sending messages through the REST API.

Related Articles