---
url: >-
  https://docs.corbitaltech.dev/products/whatsmark-saas/integrations/whatsapp-webhook-forwarding.md
description: >-
  Forward WhatsApp events to external automation platforms like N8N, Zapier,
  Make.com for powerful automation workflows.
---

# WhatsApp Webhook Forwarding

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

## 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

::: tip What's the Difference?
This feature is different from [N8N Webhook Integration](./n8n-webhook-integration.md). 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

```mermaid
graph LR
    A[WhatsApp Business API] -->|Webhook Event| B[WhatsMarkSaaS]
    B -->|Transform & Forward| C[N8N / Zapier / Make.com]
    C -->|Trigger Actions| D[Google Sheets]
    C -->|Send Alerts| E[Slack / Email]
    C -->|Update Records| F[CRM / Database]
```

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**

::: warning 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:

::: code-group

```txt [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
```

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

```txt [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

::: tip 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

```json
{
  "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

```json
{
  "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)

```javascript
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');
}
```

::: tip 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&#x20;

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

**N8N Workflow:**

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

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

***

### 2. Create Support Tickets from WhatsApp&#x20;

**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

::: code-group

```json [Webhook Config]
{
  "httpMethod": "POST",
  "path": "whatsapp-events",
  "responseMode": "onReceived",
  "responseCode": 200
}
```

```javascript [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

```javascript
// 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**

```bash
# 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.

```javascript
// 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](./whatsapp-webhook-format-reference.md).