Set Up WhatsApp Webhooks for Real-Time Notifications

Auto-reply with Shopify order status, forward urgent messages to Slack, log conversations to HubSpot. Real-time WhatsApp webhook event-driven automation for developers.

Webhooks (all plans) — real-time notifications at no extra cost. Instead of polling the API every few seconds, MoltFlow pushes WhatsApp webhook events to your server the moment they occur. Real-time event delivery with HMAC SHA-512 verification — MoltFlow webhooks are enterprise-grade, not fire-and-forget.

This guide walks you through creating your first webhook, testing delivery, and securing it with HMAC signature verification.

What You'll Need

Before starting, make sure you have:

• An HTTP endpoint that accepts POST requests — This can be your own server, an n8n WhatsApp webhook URL, a Zapier webhook, or any service that can receive HTTP POSTs.
• Growth or Business plan subscription — WhatsApp webhooks are available on Growth and Business plans. Upgrade here if you're on the Free plan.
• Basic understanding of HTTP — You should know what a POST request is and how to receive JSON payloads.

If you don't have a server yet, you can use tools like Webhook.site for testing, or follow our n8n WhatsApp integration guide to set up a visual webhook processor for event-driven workflows.

How Webhooks Work

Here's the flow:

1. Something happens in MoltFlow — A customer sends a message, your WhatsApp session reconnects, or a lead is captured from a monitored group.
2. MoltFlow sends an HTTP POST — Within milliseconds, MoltFlow sends a POST request to your configured webhook URL with the event data as JSON.
3. Your server processes the event — You can log it, trigger another action, update your CRM, send a Slack notification — whatever your workflow requires.
4. Your server responds with 200 OK — MoltFlow marks the webhook as successfully delivered.

If your server doesn't respond with a 200-level status code, MoltFlow will retry the delivery with exponential backoff (up to 5 retries over 24 hours).

Step 1: Navigate to Webhook Settings

From your MoltFlow dashboard:

1. Click Webhooks in the left sidebar

You'll see the webhook management page, which displays:

• Configured endpoints with their URLs (truncated for security)
• Subscribed events for each endpoint
• Last delivery status (success, failed, retrying)
• Failure count (if delivery is failing repeatedly)

If this is your first time, the page will be empty.

Step 2: Create a Webhook Endpoint

Click the "Create Webhook" button in the top-right corner.

A modal will appear asking for:

Webhook URL

Enter the full URL where MoltFlow should send events. Examples:

• https://yourserver.com/webhook/moltflow
• https://yourapp.n8n.cloud/webhook/abc123
• https://hooks.zapier.com/hooks/catch/123456/xyz789/

Make sure the URL is:

• HTTPS (required for security — HTTP is not allowed in production)
• Publicly accessible (MoltFlow's servers must be able to reach it)

Secret (Optional but Recommended)

Enter a secret key that MoltFlow will use to sign each webhook payload. This lets you verify that incoming requests are actually from MoltFlow and not from an attacker.

Generate a strong random string (32+ characters). Example:

openssl rand -base64 32

Save this secret securely (environment variable, secrets manager). You'll need it on your server to verify signatures.

Click Create

MoltFlow will create the webhook and show it in your list.

API equivalent:

curl -X POST https://apiv2.waiflow.app/api/v2/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourserver.com/webhook/moltflow",
    "secret": "your-generated-secret",
    "events": ["message.received"]
  }'

Step 3: Select Events to Subscribe To

After creating the webhook, click Edit to configure which events you want to receive.

Available Events

Check the boxes for the events you care about. You can subscribe to all events or just specific ones.

Common use cases for WhatsApp webhook event-driven automation:

• Customer support automation — Subscribe to message.received to trigger auto-replies, create support tickets, or log conversations.
• Status monitoring — Subscribe to session.status_changed to get real-time notifications when your WhatsApp connection drops.
• Lead pipeline — Subscribe to lead.captured to add new leads to your CRM in real-time with WhatsApp webhooks.

Click Save.

Step 4: Test Webhook Delivery

Now let's verify that MoltFlow can successfully deliver events to your endpoint.

Send a Test Event

Back on the Webhooks page, find your newly created webhook and click "Send Test Event".

MoltFlow will send a sample payload to your URL:

{
  "event": "webhook.test",
  "timestamp": "2026-02-13T10:30:00Z",
  "data": {
    "message": "This is a test event from MoltFlow"
  }
}

Check Your Server Logs

Switch to your server or webhook receiver and check the logs. You should see the incoming POST request with the test payload.

Example with Webhook.site:

If you used Webhook.site for testing, refresh the page. You'll see the test request appear with full headers and body.

Example with n8n:

If you're using n8n, your webhook trigger node should show the test event in the execution history.

Verify Delivery Status

Back in MoltFlow, the webhook's "Last Delivery" status should show Success (green). If it shows Failed (red), check:

• Is your URL correct and publicly accessible?
• Is your server responding with a 200-level status code?
• Are there firewall rules blocking MoltFlow's servers?

Step 5: Secure Your Webhook

Without signature verification, anyone who discovers your webhook URL can send fake events to your server. HMAC verification prevents this.

How HMAC Works

When you configure a webhook secret:

1. MoltFlow signs the payload — Before sending, MoltFlow computes an HMAC signature of the raw request body using your secret and SHA-512.
2. Signature is included in headers — The signature is sent in the X-Webhook-Hmac header. The algorithm is in X-Webhook-Hmac-Algorithm (always sha512).
3. Your server verifies — When you receive a webhook, compute the HMAC of the raw body using your stored secret. If it matches the header signature, the request is authentic.

Verification Code (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(req, secret) {
  const signature = req.headers['x-webhook-hmac'];
  const algorithm = req.headers['x-webhook-hmac-algorithm'];

  if (!signature || algorithm !== 'sha512') {
    return false;
  }

  // Compute HMAC of raw body
  const hmac = crypto.createHmac('sha512', secret);
  hmac.update(req.rawBody); // Important: use raw body, not parsed JSON
  const computedSignature = hmac.digest('hex');

  // Constant-time comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedSignature)
  );
}

// Express middleware example
app.post('/webhook/moltflow', express.raw({type: 'application/json'}), (req, res) => {
  const secret = process.env.MOLTFLOW_WEBHOOK_SECRET;

  if (!verifyWebhookSignature(req, secret)) {
    return res.status(401).json({error: 'Invalid signature'});
  }

  // Signature is valid — process the event
  const event = JSON.parse(req.body);
  console.log('Received event:', event);

  res.status(200).json({received: true});
});

Verification Code (Python)

import hmac
import hashlib

def verify_webhook_signature(request_body: bytes, signature: str, secret: str) -> bool:
    """Verify HMAC signature from MoltFlow webhook."""
    computed_signature = hmac.new(
        secret.encode(),
        request_body,
        hashlib.sha512
    ).hexdigest()

    # Constant-time comparison
    return hmac.compare_digest(signature, computed_signature)

# FastAPI example
from fastapi import Request, HTTPException

@app.post("/webhook/moltflow")
async def handle_webhook(request: Request):
    signature = request.headers.get("x-webhook-hmac")
    algorithm = request.headers.get("x-webhook-hmac-algorithm")

    if not signature or algorithm != "sha512":
        raise HTTPException(status_code=401, detail="Missing or invalid signature")

    body = await request.body()
    secret = os.getenv("MOLTFLOW_WEBHOOK_SECRET")

    if not verify_webhook_signature(body, signature, secret):
        raise HTTPException(status_code=401, detail="Invalid signature")

    # Signature is valid — process the event
    event = await request.json()
    print(f"Received event: {event}")

    return {"received": True}

Important: Always use the raw request body for HMAC computation, not the parsed JSON. Parsing can change whitespace, key order, etc., which will break the signature.

Example Event Payloads

Here's what real events look like:

message.received

Sent when a customer sends you a WhatsApp message:

{
  "event": "message.received",
  "timestamp": "2026-02-13T10:30:00Z",
  "data": {
    "session_id": "abc123",
    "from": "1234567890",
    "from_name": "John Doe",
    "body": "Hello! I have a question about my order.",
    "message_id": "wamid.xyz789",
    "chat_id": "[email protected]"
  }
}

session.status_changed

Sent when your WhatsApp session status changes:

{
  "event": "session.status_changed",
  "timestamp": "2026-02-13T10:35:00Z",
  "data": {
    "session_id": "abc123",
    "old_status": "working",
    "new_status": "failed",
    "reason": "Phone disconnected"
  }
}

lead.captured

Sent when a new lead is captured from a monitored group:

{
  "event": "lead.captured",
  "timestamp": "2026-02-13T10:40:00Z",
  "data": {
    "session_id": "abc123",
    "group_id": "[email protected]",
    "phone": "9876543210",
    "name": "Jane Smith",
    "message_preview": "I'm interested in your product!",
    "captured_at": "2026-02-13T10:40:00Z"
  }
}

Handling Failures

Retry Logic

If your server doesn't respond with a 200-level status code (200, 201, 204), MoltFlow will retry delivery:

• 1st retry — After 1 minute
• 2nd retry — After 5 minutes
• 3rd retry — After 15 minutes
• 4th retry — After 1 hour
• 5th retry — After 6 hours

After 5 failed attempts, the webhook is paused and you'll see a warning on the Webhooks page.

Debugging Failed Deliveries

If deliveries are failing:

1. Check the Last Delivery status on the Webhooks page
2. Click the webhook to see error details (timeout, 500 error, connection refused, etc.)
3. Fix your endpoint (check firewall, check server is running, check response status code)
4. Click Resume to unpause the webhook
5. Click Retry Failed to redeliver the queued events

Best Practices

• Respond quickly — Your server should respond with 200 OK within 5 seconds. Do heavy processing (like database writes or API calls) in a background job after responding.
• Handle duplicates — In rare cases (e.g., network glitch), MoltFlow might deliver the same event twice. Use the event timestamp and message_id to deduplicate.
• Monitor failures — Set up alerts if your webhook failure count exceeds a threshold.

What's Next?

Now that you have WhatsApp webhooks configured, explore these event-driven integration options:

• Connect MoltFlow to n8n — Process webhook events visually with 500+ app integrations
• REST API Quick Start — Trigger actions back to MoltFlow from your webhook handler
• Send Bulk Messages — Combine webhooks with bulk sends for follow-up automation
• Monitor WhatsApp Groups — Capture leads from groups and send webhook notifications

WhatsApp webhooks are the backbone of real-time automation. Use them to connect MoltFlow to your CRM, support desk, analytics, and business logic with event-driven workflows.

Developers love MoltFlow's API. See the full reference docs.

Need help? Contact support via the dashboard chat or email us at [email protected]. We typically respond within 2-4 hours.