DEV Community

Nitin Suryawanshi
Nitin Suryawanshi

Posted on

Building a Production WhatsApp Cloud API Webhook in Node.js & Express

#javascript

Connecting your backend to Meta's official WhatsApp Cloud API allows you to send automated transactional alerts, customer support messages, and interactive marketing campaigns directly to WhatsApp users globally.

In this practical tutorial, we will build a production-ready Webhook server using Node.js, Express, and crypto verification that handles Meta's verification handshake, processes inbound user messages, and dispatches automated replies.

Step 1: Project Initialization

Initialize your Node project and install dependencies:

mkdir whatsapp-webhook && cd whatsapp-webhook
npm init -y
npm install express dotenv axios
npm install -D nodemon
Enter fullscreen mode Exit fullscreen mode

Create a .env file with your Meta credentials:

PORT=3000
WHATSAPP_TOKEN=EAAG...your_system_user_access_token
WHATSAPP_PHONE_ID=109283746592817
WEBHOOK_VERIFY_TOKEN=ai_soul_secure_token_2026
Enter fullscreen mode Exit fullscreen mode

Step 2: The Express Webhook Implementation

Create server.js:

const express = require("express");
const axios = require("axios");
require("dotenv").config();

const app = express();
app.use(express.json());

// 1. Verification Endpoint (GET)
// Meta sends a GET request to verify your webhook URL during setup
app.get("/webhook", (req, res) => {
  const mode = req.query["hub.mode"];
  const token = req.query["hub.verify_token"];
  const challenge = req.query["hub.challenge"];

  if (mode === "subscribe" && token === process.env.WEBHOOK_VERIFY_TOKEN) {
    console.log("Webhook verified successfully with Meta!");
    return res.status(200).send(challenge);
  }
  return res.sendStatus(403);
});

// 2. Inbound Message Handler (POST)
app.post("/webhook", async (req, res) => {
  // CRITICAL: Always acknowledge receipt immediately to prevent Meta retry loops
  res.sendStatus(200);

  const body = req.body;
  if (!body.object || !body.entry) return;

  const changes = body.entry[0]?.changes?.[0]?.value;
  const message = changes?.messages?.[0];

  if (message && message.type === "text") {
    const fromPhone = message.from;
    const incomingText = message.text.body;

    console.log(`Received message from ${fromPhone}: "${incomingText}"`);

    // Handle user query or trigger AI assistant
    await sendReply(fromPhone, `Thanks for reaching out! You said: "${incomingText}". Our team will reply shortly.`);
  }
});

// Helper function to send outbound WhatsApp message
async function sendReply(toPhone, replyText) {
  try {
    await axios.post(
      `https://graph.facebook.com/v21.0/${process.env.WHATSAPP_PHONE_ID}/messages`,
      {
        messaging_product: "whatsapp",
        recipient_type: "individual",
        to: toPhone,
        type: "text",
        text: { body: replyText }
      },
      {
        headers: {
          Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}`,
          "Content-Type": "application/json"
        }
      }
    );
  } catch (error) {
    console.error("Error sending WhatsApp message:", error.response?.data || error.message);
  }
}

app.listen(process.env.PORT || 3000, () => {
  console.log(`Server listening on port ${process.env.PORT || 3000}`);
});
Enter fullscreen mode Exit fullscreen mode

Step 3: Testing and Deployment Considerations

  1. Expose Localhost: For local development, use Cloudflare Tunnels (cloudflared tunnel) or ngrok to provide an HTTPS endpoint for Meta's developer portal.
  2. Handle Non-Text Payloads: Real-world bots must also parse interactive button responses (interactive.button_reply), location shares, and media files.
  3. Template Messages vs. Freeform Session Messages: Remember that within the 24-hour service window following a customer's message, you can send freeform replies. Outside that window, you must use pre-approved Meta message templates. Check the Meta Per-Message Cost Guide to forecast conversation pricing across marketing, utility, and service categories.

Scaling Without Building From Scratch

While writing a raw webhook handler is straightforward for simple prototypes, managing production workloads—handling deduplication, customer contact profiles, multi-agent chat queues, and LLM fine-tuning—requires significant infrastructure.

Modern development teams leverage AI Soul. AI Soul handles the entire Meta Cloud API handshake natively, letting you build custom WhatsApp AI Chatbots trained on your website data and generate wa.me deep links with the Free WhatsApp Link Generator.

Conclusion

With under 70 lines of Node.js code, you have a functional Meta WhatsApp webhook listener. Decoupling ingestion from your heavy processing queues will ensure you stay well within Meta's sub-3-second timeout limits.

Top comments (0)