WhatsApp Webhook Forwarding

v1.6.0+

Automatically forward WhatsApp Business events to external platforms like N8N, Zapier, Make.com, or your custom webhook endpoints for powerful automation workflows.

• Overview
• How It Works
• Supported WhatsApp Events
  • Message Events
  • Account & Business Events
  • Template Events
  • Phone Number Events
• Quick Setup Guide
  • Step 1: Configure WhatsApp Webhook Settings
  • Step 2: Set Up Your Webhook Endpoint
  • Step 3: Enter Webhook URL
  • Step 4: Test the Integration
• Webhook Payload Format
  • Structure Overview
  • Example: Message Received
• Event Type Reference
  • Message Events
  • Template Events
  • Account Events
• Security Features
  • Signature Verification
  • Verify Signature (Node.js)
• Common Use Cases
  • 1. Auto-Save Conversations to Google Sheets Beginner Friendly
  • 2. Create Support Tickets from WhatsApp Popular
  • 3. Alert Team on Slack for New Messages
  • 4. Track Message Delivery & Engagement
  • 5. Smart CRM Updates
• Platform-Specific Setup
  • N8N Setup (Detailed)
• Troubleshooting
  • Webhooks Not Arriving
  • Some Events Not Forwarding
  • Webhook Timing Out
  • Duplicate Webhooks
• Best Practices
  • 1. Start Small
  • 2. Secure Your Endpoint
  • 3. Handle Failures Gracefully
  • 4. Monitor Performance
  • 5. Optimize for Scale
• Advanced Configuration
  • Custom HTTP Methods
  • Filtering Events
  • Multiple Endpoints
• Technical Reference

Overview

WhatsApp Webhook Forwarding enables real-time forwarding of WhatsApp events from the WhatsApp Business API to external automation platforms. This powerful feature allows you to:

• 🤖 Automate customer responses - Trigger workflows when messages arrive
• 📊 Track analytics - Send WhatsApp data to analytics tools
• 💾 Sync conversations - Keep external databases updated with chat history
• 🔔 Get instant notifications - Alert your team on Slack, email, or SMS
• 🔗 Integrate systems - Connect WhatsApp with CRMs, help desks, or custom apps
• 🔄 Build workflows - Create complex multi-step automations based on WhatsApp events

What's the Difference?

This feature is different from N8N Webhook Integration. While N8N integration sends tenant events (contacts, sources, statuses), WhatsApp Webhook Forwarding sends WhatsApp-specific events (messages, delivery statuses, read receipts, template updates, etc.) directly from the WhatsApp Business API.

How It Works

When WhatsApp events occur (like incoming messages or delivery confirmations), WhatsMarkSaaS:

1. Receives the raw WhatsApp webhook payload
2. Transforms it into a standardized N8N-compatible format
3. Forwards it securely to your configured endpoint
4. Includes HMAC signature for verification

Supported WhatsApp Events

Message Events

Event Type	Description	Use Cases
Messages Received	Customer sends a message	Auto-responses, ticket creation, logging
Message Echoes	Your business sends a message	Message tracking, backup, analytics
Message Status	Delivery/read confirmations	Tracking engagement, CRM updates

Account & Business Events

Event Type	Description	Use Cases
Account Alerts	Important account notifications	Alert admin team, monitor compliance
Account Updates	Account settings changed	Audit logging, sync configurations
Business Updates	Business profile changes	Keep CRM profile updated

Template Events

Event Type	Description	Use Cases
Template Status Updates	Template approved/rejected	Notify marketing team, track approvals
Template Quality Updates	Template quality score changes	Quality monitoring, alerts

Phone Number Events

Event Type	Description	Use Cases
Phone Quality Updates	Phone number quality rating changed	Quality monitoring, compliance
Phone Name Updates	Display name updated	Sync profile changes

Quick Setup Guide

Step 1: Configure WhatsApp Webhook Settings

1. Navigate to Settings → WhatsApp → Webhooks in your tenant account
2. Toggle "Enable Webhooks Resend" to ON
3. Select the WhatsApp event types you want to forward
4. Click Save

Tenant-Level Configuration

WhatsApp Webhook Forwarding is configured per tenant. Each tenant can have their own webhook URL and event selections.

Step 2: Set Up Your Webhook Endpoint

Choose your automation platform:

N8N

1. Create a new N8N workflow
2. Add a "Webhook" node
3. Configure:
   - HTTP Method: POST
   - Path: /webhook/whatsapp-events
   - Response: Return immediately
4. Copy the webhook URL

Zapier

1. Create a new Zap
2. Choose trigger: "Webhooks by Zapier"
3. Select "Catch Hook"
4. Copy the provided webhook URL

Make.com

1. Create a new scenario
2. Add "Webhooks" module
3. Select "Custom webhook"
4. Copy the generated webhook URL

Step 3: Enter Webhook URL

Back in WhatsMarkSaaS:

1. Go to Settings → WhatsApp → Webhooks
2. Paste your webhook URL in "WhatsApp Received Data Resend To" field
3. Select HTTP method: POST (recommended)
4. Click Save

Step 4: Test the Integration

1. Send a test WhatsApp message to your business number
2. Check your automation platform to verify webhook received
3. Inspect the payload structure

Testing Tip

Start with only "Messages" event selected. Once verified working, enable additional event types as needed.

Webhook Payload Format

All WhatsApp webhooks are sent in a standardized N8N-compatible format:

Structure Overview

{
  "event": {
    "id": "evt_1767263928_7KGQvXqbFF",
    "type": "whatsapp.message.received",
    "timestamp": "2026-01-01T10:38:48+00:00",
    "version": "1.0"
  },
  "tenant": {
    "id": 3,
    "name": "Your Company"
  },
  "data": {
    "resource": {
      "type": "message",
      "id": "wamid.xxx",
      "attributes": {
        /* Message details */
      }
    },
    "relationships": {
      "contact": {
        /* Customer info */
      },
      "metadata": {
        /* WhatsApp phone number info */
      }
    }
  },
  "whatsapp": {
    "original_payload": {
      /* Complete raw WhatsApp webhook */
    }
  },
  "metadata": {
    "source": "whatsapp_webhook_forward",
    "environment": "production",
    "request_id": "uuid"
  }
}

Example: Message Received

{
  "event": {
    "id": "evt_1767263928_7KGQvXqbFF",
    "type": "whatsapp.message.received",
    "timestamp": "2026-01-01T10:38:48+00:00",
    "version": "1.0"
  },
  "tenant": {
    "id": 3,
    "name": "Acme Corp"
  },
  "data": {
    "resource": {
      "type": "message",
      "id": "wamid.HBgMOTE5OTI1MTE5Mjg0FQIAEhgWM0VCMDE1NDRCMTFBMDQ1RTlFM0NFMwA=",
      "attributes": {
        "message_id": "wamid.HBgMOTE5OTI1MTE5Mjg0FQIAEhgWM0VCMDE1NDRCMTFBMDQ1RTlFM0NFMwA=",
        "from": "919876543210",
        "timestamp": "1767263926",
        "type": "text",
        "text": "Hello, I need help with my order",
        "context": null
      }
    },
    "relationships": {
      "contact": {
        "wa_id": "919876543210",
        "name": "John Doe"
      },
      "metadata": {
        "phone_number_id": "339141689277134",
        "display_phone_number": "919428735270"
      }
    }
  },
  "whatsapp": {
    "original_payload": {
      "object": "whatsapp_business_account",
      "entry": [
        /* Full WhatsApp webhook payload */
      ]
    }
  },
  "metadata": {
    "source": "whatsapp_webhook_forward",
    "environment": "production",
    "request_id": "595bbcf8-93bf-418b-8209-3343c76ad852"
  }
}

Event Type Reference

Message Events

whatsapp.message.received

Triggered when a customer sends a message to your business.

Common Use Cases:

• Create support tickets automatically
• Log conversations to Google Sheets
• Trigger chatbot responses
• Send notifications to support team

Example N8N Workflow:

Webhook (Message Received)
  ↓
Filter (Check for keywords)
  ↓
Create Ticket in Help Desk
  ↓
Send Slack Notification

whatsapp.message.delivered

Triggered when your message is successfully delivered to the customer's device.

Common Use Cases:

• Track delivery rates
• Update CRM with delivery status
• Confirm important messages reached customers

whatsapp.message.read

Triggered when the customer reads your message (blue checkmarks).

Common Use Cases:

• Track engagement metrics
• Identify hot leads (fast readers)
• Follow up on unread messages

whatsapp.message.sent

Triggered when your business sends a message (echo event).

Common Use Cases:

• Backup all outgoing messages
• Track message volume
• Log agent activity

whatsapp.message.failed

Triggered when a message fails to send.

Common Use Cases:

• Alert support team
• Retry failed messages
• Track delivery issues

Template Events

whatsapp.template.status_updated

Triggered when message template approval status changes.

Possible statuses:

• APPROVED - Template approved and ready to use
• REJECTED - Template rejected by WhatsApp
• PENDING - Template under review

Common Use Cases:

• Notify marketing team when templates are approved
• Track rejected templates for improvement
• Automate template workflow

whatsapp.template.quality_updated

Triggered when template quality score changes.

Common Use Cases:

• Monitor template performance
• Alert when quality drops
• Optimize message templates

Account Events

whatsapp.account.alert

Important notifications about your WhatsApp Business account.

Common Use Cases:

• Alert admin immediately
• Log all account alerts
• Monitor compliance issues

Security Features

Signature Verification

Every webhook includes an HMAC-SHA256 signature for verification.

Headers Sent:

X-Webhook-Signature: <hmac-sha256-hash>
X-Webhook-Event: whatsapp.message.received
X-Webhook-Timestamp: 2026-01-01T10:38:48+00:00
X-Webhook-Format: n8n
User-Agent: whatsmark-Webhook/1.0

Verify Signature (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
const signature = req.headers['x-webhook-signature'];
const secret = process.env.WEBHOOK_SECRET;

if (!verifyWebhookSignature(req.body, signature, secret)) {
  return res.status(403).send('Invalid signature');
}

Signature Secret

Contact your system administrator to get the webhook signing secret. When using N8N, Zapier, or Make.com, signature verification is handled automatically.

Common Use Cases

1. Auto-Save Conversations to Google Sheets Beginner Friendly

Scenario

Keep a backup of all customer conversations for compliance and record-keeping.

N8N Workflow:

Webhook (Message Received)
  ↓
Set Variables (Extract phone, message, timestamp)
  ↓
Google Sheets (Append Row)

Result

Every message automatically logged to spreadsheet with timestamp and customer info.

---

2. Create Support Tickets from WhatsApp Popular

Scenario: Convert WhatsApp messages into support tickets.

N8N Workflow:

Webhook (Message Received)
  ↓
Check Contact in CRM
  ↓
Create Ticket in Help Desk
  ↓
Send Auto-Reply

Result: Seamless multi-channel support system.

---

3. Alert Team on Slack for New Messages

Scenario: Notify support team instantly when customers message.

N8N Workflow:

Webhook (Message Received)
  ↓
Format Message
  ↓
Send to Slack Channel

Result: Team gets instant Slack notifications with customer name, phone, and message.

---

4. Track Message Delivery & Engagement

Scenario: Measure campaign effectiveness.

N8N Workflow:

Webhook (Message Status)
  ↓
Switch by Status (delivered/read/failed)
  ↓
Update Analytics Database
  ↓
Calculate Metrics

Result: Real-time delivery and read rate analytics.

---

5. Smart CRM Updates

Scenario: Keep CRM updated with WhatsApp activity.

N8N Workflow:

Webhook (Message Received/Sent)
  ↓
Find Contact in CRM
  ↓
Update: Last Contact Date, Message Count
  ↓
Add Note with Message

Result: CRM always has latest customer interaction data.

Platform-Specific Setup

N8N Setup (Detailed)

1. Create Webhook Node

Webhook Config

{
  "httpMethod": "POST",
  "path": "whatsapp-events",
  "responseMode": "onReceived",
  "responseCode": 200
}

Extract Data

// Code Node - Extract Data
const payload = $json;
return {
  messageId: payload.data.resource.id,
  from: payload.data.resource.attributes.from,
  text: payload.data.resource.attributes.text,
  contactName: payload.data.relationships.contact.name,
  timestamp: payload.event.timestamp,
  eventType: payload.event.type
};

2. Route by Event Type

// Switch Node
switch (eventType) {
  case 'whatsapp.message.received':
    return [0]; // Output 0
  case 'whatsapp.message.delivered':
    return [1]; // Output 1
  case 'whatsapp.message.read':
    return [2]; // Output 2
  default:
    return [3]; // Output 3
}

Troubleshooting

Webhooks Not Arriving

Check 1: Verify Settings

• Go to Settings → WhatsApp → Webhooks
• Ensure toggle is ON
• Verify URL is correct (no typos)
• Check event types are selected

Check 2: Test Endpoint

# Test your webhook URL
curl -X POST https://your-webhook-url.com \
  -H "Content-Type: application/json" \
  -d '{"test": "data"}'

Check 3: Check Logs

• In N8N: Check Executions tab
• In Zapier: Check Task History
• In Make.com: Check Execution History

Some Events Not Forwarding

Problem: Only some webhooks are received, not all.

Solutions:

1. Go to Settings → WhatsApp → Webhooks
2. Review selected event fields
3. Enable missing event types
4. Save and test again

Webhook Timing Out

Problem: Webhooks fail with timeout errors.

Solution: Optimize your endpoint response time.

Best Practices:

• Return 200 OK immediately
• Process data asynchronously using queues
• Use background jobs for heavy operations
• Don't wait for external API calls before responding

Duplicate Webhooks

WhatsMarkSaaS prevents duplicate processing automatically using message IDs. If you still see duplicates:

Solution: Implement idempotency in your endpoint.

// Example: Track processed events
const processedEvents = new Set();

if (processedEvents.has(webhook.event.id)) {
  return { status: 'already_processed' };
}
}

processedEvents.add(webhook.event.id);
// Process webhook...

Best Practices

1. Start Small

• Begin with only "Messages" event type
• Verify it works correctly
• Gradually add more event types

2. Secure Your Endpoint

• Use HTTPS only (not HTTP)
• Implement signature verification for custom endpoints
• Keep webhook URL private
• Monitor for unauthorized requests

3. Handle Failures Gracefully

• Return 200 OK quickly
• Use queues for processing
• Implement retry logic
• Log errors for debugging

4. Monitor Performance

• Track webhook delivery success rate
• Monitor endpoint response times
• Set up alerts for failures
• Review logs regularly

5. Optimize for Scale

• Use background processing
• Implement rate limiting
• Cache frequently accessed data
• Use database indexes

Advanced Configuration

Custom HTTP Methods

While POST is recommended, you can use other HTTP methods:

Available Methods:

• POST (Recommended) - Data in request body
• GET - Data as query parameters
• PUT - Update operations
• PATCH - Partial updates

Filtering Events

Selective Forwarding: Only forward events for specific conditions by configuring event field selection in settings.

Multiple Endpoints

Current Limitation: One webhook URL per tenant.

Workaround: Use N8N to fan out to multiple destinations:

Webhook (from WhatsMarkSaaS)
  ↓
  ├─→ Google Sheets
  ├─→ Slack
  ├─→ CRM API
  └─→ Custom Database

Technical Reference

For complete technical documentation including:

• Full payload schemas
• All event types
• Code examples in multiple languages
• Architecture diagrams
• Implementation details

See the WhatsApp Webhook Format Technical Reference.