DEV Community

L.
L.

Posted on

🟢 Build a WhatsApp Webhook Server Using the Official Facebook Business SDK in TypeScript 🚀

We'll build a webhook server that:

  • Receives incoming messages and status updates
  • Verifies signatures securely
  • Uses the official SDK for parsing and handling events
  • Is ready to be extended into a chatbot or customer support tool

TL;DR: Learn how to create a secure, production-ready webhook server in Node.js + TypeScript that receives messages from WhatsApp using the official Facebook Node.js Business SDK. This setup works directly with WhatsApp Business API (via Meta/Facebook), so it’s perfect for chatbots, automation, and customer messaging integrations.

💬 Why Use the Facebook Business SDK?

Instead of manually parsing WhatsApp webhook payloads, you can use the officially supported SDK:

npm install --save facebook-nodejs-business-sdk
Enter fullscreen mode Exit fullscreen mode

This gives you:

  • Verified request signature validation 🔐
  • Built-in message/status parsing ✅
  • Consistent event types 🧩
  • Better error handling 🛡️

Perfect for building scalable WhatsApp integrations.

🧰 Tech Stack

We'll use:

  • Node.js + Express.js
  • TypeScript
  • Express middleware
  • facebook-nodejs-business-sdk
  • Optional: Zod for schema validation
  • Optional: dotenv for environment variables

📦 Step 1: Setup Your Project 

mkdir whatsapp-webhook-server cd whatsapp-webhook-server npm init -y npm install express body-parser dotenv cors helmet morgan npm install --save facebook-nodejs-business-sdk npm install --save-dev typescript ts-node @types/express zod
Enter fullscreen mode Exit fullscreen mode

Create tsconfig.json:

{ "compilerOptions": { "target": "ES2020", "module": "CommonJS", "esModuleInterop": true, "strict": true, "outDir": "./dist" }, "include": ["src/**/*"] }
Enter fullscreen mode Exit fullscreen mode

🏗️ Step 2: Basic Server Setup

Create src/index.ts:

import express from 'express'; import bodyParser from 'body-parser'; import dotenv from 'dotenv'; dotenv.config(); const app = express(); const PORT = process.env.PORT || 3000; // Middleware app.use(bodyParser.json()); app.use(express.json()); // Health check route app.get('/health', (req, res) => { res.status(200).send('✅ WhatsApp webhook server is running!'); }); app.listen(PORT, () => { console.log(`🚀 WhatsApp webhook server is listening on port ${PORT}`); });
Enter fullscreen mode Exit fullscreen mode

Run it with:

npx ts-node src/index.ts
Enter fullscreen mode Exit fullscreen mode

Test:

curl http://localhost:3000/health
Enter fullscreen mode Exit fullscreen mode

Output: ✅ WhatsApp webhook server is running!

🪝 Step 3: Create WhatsApp Webhook Endpoint

WhatsApp sends JSON payloads to your webhook URL when users send messages or message statuses change.

Let’s create /whatsapp endpoint using the SDK.

Create src/webhookHandler.ts:

import { Request, Response } from 'express'; import { Webhook, Message } from 'facebook-nodejs-business-sdk'; const APP_SECRET = process.env.WHATSAPP_APP_SECRET as string; export const handleWhatsAppWebhook = (req: Request, res: Response) => { try { // Initialize Webhook class with app secret const webhook = new Webhook(APP_SECRET); // Validate and parse the request const isValid = webhook.validateRequest(req); if (!isValid) { return res.status(400).send('Invalid signature'); } const payload = webhook.getPayload(); // Handle challenge for initial setup if (payload.object === 'whatsapp_business_account') { payload.entry.forEach((entry: any) => { entry.changes.forEach((change: any) => { const value = change.value; const message = value.messages?.[0]; if (message) { console.log("💬 Incoming message:", message); // You can now reply using WhatsApp Cloud API } const status = value.statuses?.[0]; if (status) { console.log("🔄 Message status updated:", status); } }); }); // Confirm receipt return res.status(200).send('EVENT_RECEIVED'); } res.status(400).send('Unknown object type'); } catch (err) { console.error("⚠️ Error handling webhook:", err); res.status(500).send('Internal Server Error'); } };
Enter fullscreen mode Exit fullscreen mode

Add route in index.ts:

import { handleWhatsAppWebhook } from './webhookHandler'; app.post('/whatsapp', handleWhatsAppWebhook);
Enter fullscreen mode Exit fullscreen mode

🌍 Step 4: Expose Locally for Testing

Use ngrok to get a public URL:

npx ngrok http 3000
Enter fullscreen mode Exit fullscreen mode

You’ll get something like https://abc123.ngrok.io.

Use this URL when setting up your webhook in the Meta Developer Portal under your WhatsApp Business App settings.

Set the callback URL to:

https://abc123.ngrok.io/whatsapp
Enter fullscreen mode Exit fullscreen mode

And verify token to match your app logic.

🧪 Step 5: Add Schema Validation (Optional)

Validate the shape of incoming WhatsApp events before processing.

Example schema for message object:

// src/schemas/whatsappSchema.ts import { z } from 'zod'; export const WhatsAppMessageSchema = z.object({ from: z.string(), id: z.string(), timestamp: z.string(), text: z.object({ body: z.string() }).optional(), type: z.enum(['text', 'image', 'video', 'document', 'audio']), });
Enter fullscreen mode Exit fullscreen mode

In handler:

import { WhatsAppMessageSchema } from '../schemas/whatsappSchema'; if (message) { const parsed = WhatsAppMessageSchema.safeParse(message); if (parsed.success) { console.log("✅ Valid message received:", parsed.data); } else { console.warn("❌ Invalid message structure"); } }
Enter fullscreen mode Exit fullscreen mode

Now malformed messages are caught early ⚠️.

🔄 Step 6: Acknowledge Fast, Process Later

Always respond quickly to avoid retries.

Refactor to process asynchronously:

setTimeout(async () => { await processIncomingMessage(parsed.data); }, 0); res.status(200).send("EVENT_RECEIVED");
Enter fullscreen mode Exit fullscreen mode

Or better yet, push to a queue system like BullMQ or Redis.

🧼 Step 7: Prepare for Production

  • Store logs securely (use Winston/Pino)
  • Set up rate limiting (express-rate-limit)
  • Rotate secrets regularly
  • Deploy to Vercel, Render, AWS, or Heroku 🚀
  • Use HTTPS (required by WhatsApp)

✅ Summary: What You’ve Built

Feature Description
✔️ Webhook Receiver /whatsapp endpoint accepting POSTs
✔️ Signature Verification Uses Facebook SDK for HMAC validation
✔️ Event Parsing Parses messages/statuses out-of-the-box
✔️ Async Processing Acknowledge fast, process later
✔️ External Integration Works with WhatsApp Business API
✔️ Secure by Default Uses SDK, logging, secret checks

🚨 Final Tips

  • Always respond within seconds ⚡
  • Never throw unhandled errors ⚠️
  • Log everything during dev 📜
  • Store events for audit/retry (optional) 🗂️
  • Rotate secrets regularly 🔁

📢 Share This Post

If you found this useful, share it with your fellow devs and help others build secure, robust WhatsApp webhook servers too!

Top comments (0)