---
url: >-
  https://docs.corbitaltech.dev/products/whatsmark-saas/ref-docs/whatsapp-webhook-forwarding.md
description: >-
  Automatically forward WhatsApp events to external automation platforms like
  N8N, Zapier, Make.com, or your custom applications
---

# WhatsApp Webhook Forwarding

Connect your WhatsApp Business messages and events to powerful automation tools like N8N, Zapier, Make.com, or any custom webhook endpoint.

## What is Webhook Forwarding?

Webhook forwarding allows you to automatically send WhatsApp events (like new messages, delivery statuses, read receipts) to external platforms in real-time. This enables you to:

* **Automate responses** - Trigger workflows when messages arrive
* **Track analytics** - Send data to your analytics tools
* **Sync data** - Keep external databases updated
* **Get notifications** - Alert your team on other platforms
* **Integrate systems** - Connect WhatsApp with your CRM, help desk, or custom apps

## Getting Started

### Prerequisites

Before you begin, you'll need:

* A WhatsApp Business account connected to your application
* A webhook endpoint URL (from N8N, Zapier, Make.com, or your custom server)
* Access to Settings in your account

### Quick Setup (5 minutes)

Follow these simple steps to start forwarding WhatsApp events:

#### Step 1: Enable Webhook Forwarding

1. Log in to your account
2. Navigate to **Settings** → **WhatsApp** → **Webhooks**
3. Find the **"Enable Webhooks Resend"** toggle
4. Turn it **ON** (green)

#### Step 2: Enter Your Webhook URL

1. In the **"WhatsApp Received Data Resend To"** field
2. Paste your webhook URL
   * Example: `https://your-n8n-instance.com/webhook/whatsapp`
   * Example: `https://hooks.zapier.com/hooks/catch/123456/abcdef/`
   * Example: `https://your-domain.com/api/webhooks/whatsapp`

::: tip
Make sure your URL starts with `https://` for security. HTTP URLs will work but are not recommended for production.
:::

#### Step 3: Choose HTTP Method

Select how data should be sent:

* **POST** (Recommended) - Sends data in the request body
* **GET** - Sends data as URL parameters

::: tip
Most platforms like N8N and Zapier expect POST requests. Use POST unless your endpoint specifically requires GET.
:::

#### Step 4: Select Event Types

Choose which WhatsApp events you want to forward:

**Message Events:**

* **Messages** - When customers send you messages
* **Message Echoes** - When you send messages
* **Message Status** - Delivery confirmations and read receipts

**Account & Business Events:**

* **Account Alerts** - Important notifications about your account
* **Account Updates** - Changes to your account settings
* **Business Updates** - Updates to your business profile

**Template Events:**

* **Template Status** - When message templates are approved/rejected
* **Template Quality** - Quality score changes for templates

**Phone Number Events:**

* **Phone Quality Updates** - Quality rating changes
* **Phone Name Updates** - Display name changes

::: tip Best Practice
Start with just **Messages** selected. Once you confirm it's working, add more event types as needed.
:::

#### Step 5: Save Settings

Click the **"Save Changes"** button at the bottom of the page.

**You're all set!** Your WhatsApp events will now be forwarded automatically.

***

## Using with Popular Platforms

### N8N (Recommended)

N8N is a powerful open-source automation platform that works perfectly with webhook forwarding.

**Setup in N8N:**

1. **Create a New Workflow**

   * Open your N8N instance
   * Click **"New Workflow"**

2. **Add Webhook Trigger**

   * Click the **"+"** button
   * Search for **"Webhook"**
   * Select **"Webhook"** node

3. **Configure the Webhook**

   * HTTP Method: `POST`
   * Path: Choose a path like `/whatsapp-events`
   * Authentication: None (we include signature for verification)
   * Response: `Respond Immediately`

4. **Get Your Webhook URL**

   * Click **"Test URL"** or **"Production URL"**
   * Copy the full URL shown
   * It will look like: `https://your-n8n.app/webhook/whatsapp-events`

5. **Paste URL in Settings**

   * Go back to your WhatsApp webhook settings
   * Paste the N8N URL
   * Save settings

6. **Activate the Workflow**
   * In N8N, click **"Active"** toggle to turn it ON

::: tip
Use the Production URL for live use, not the Test URL. Test URLs expire.
:::

**Example N8N Workflow Ideas:**

```
New WhatsApp Message
    ↓
Save to Google Sheets
    ↓
Send Email Notification
    ↓
Post to Slack Channel
```

```
Message Delivered
    ↓
Update Customer Record
    ↓
Send Thank You Email
```

### Zapier

1. **Create a Zap**

   * Go to zapier.com
   * Click **"Make a Zap"**

2. **Choose Trigger**

   * Search for **"Webhooks by Zapier"**
   * Select **"Catch Hook"**
   * Copy the webhook URL provided

3. **Configure in Your App**

   * Paste Zapier webhook URL in settings
   * Method: `POST`
   * Select event types
   * Save settings

4. **Test the Integration**
   * Send a test WhatsApp message
   * Check if Zapier receives the data
   * Continue building your Zap

### Make.com (formerly Integromat)

1. **Create a Scenario**

   * Log in to Make.com
   * Click **"Create a new scenario"**

2. **Add Webhook Module**

   * Click the **"+"** button
   * Search for **"Webhooks"**
   * Select **"Custom webhook"**
   * Click **"Add"**

3. **Copy Webhook Address**

   * Make.com will generate a webhook URL
   * Copy this URL

4. **Configure in Your App**

   * Paste Make.com webhook URL
   * Method: `POST`
   * Select events
   * Save

5. **Activate Scenario**
   * Send a test message
   * Make.com will capture the data structure
   * Continue building your automation

### Custom Applications

If you're sending webhooks to your own server, you'll receive data in this format:

```json
{
  "event": {
    "id": "evt_1234567890_abc123",
    "type": "whatsapp.message.received",
    "timestamp": "2026-01-01T10:30:00Z"
  },
  "tenant": {
    "id": 123,
    "name": "Your Company"
  },
  "data": {
    "resource": {
      "type": "message",
      "id": "wamid.xxx",
      "attributes": {
        "message_id": "wamid.xxx",
        "from": "919876543210",
        "timestamp": "1735728600",
        "type": "text",
        "text": "Hello, I need help!"
      }
    },
    "relationships": {
      "contact": {
        "wa_id": "919876543210",
        "name": "John Doe"
      },
      "metadata": {
        "phone_number_id": "1234567890",
        "display_phone_number": "919123456789"
      }
    }
  }
}
```

::: details Click to see all fields explained

* **event.id** - Unique identifier for this webhook event
* **event.type** - Type of event (message.received, message.delivered, etc.)
* **event.timestamp** - When the event occurred (ISO 8601 format)
* **tenant.id** - Your account/tenant ID
* **tenant.name** - Your company/account name
* **data.resource.type** - Resource type (message, status, etc.)
* **data.resource.id** - WhatsApp message ID
* **data.resource.attributes** - Event details (message content, sender, etc.)
* **data.relationships.contact** - Information about the customer
* **data.relationships.metadata** - WhatsApp account information
  :::

***

## Understanding Events

### Message Events

#### whatsapp.message.received

Triggered when a customer sends you a message.

**When to use:**

* Auto-respond to customer inquiries
* Log all incoming messages
* Notify your support team
* Trigger chatbot workflows

**Example payload:**

```json
{
  "event": {
    "type": "whatsapp.message.received"
  },
  "data": {
    "resource": {
      "attributes": {
        "from": "919876543210",
        "type": "text",
        "text": "I have a question about pricing"
      }
    }
  }
}
```

#### whatsapp.message.delivered

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

**When to use:**

* Track message delivery rates
* Update delivery status in your CRM
* Confirm important messages reached customers

#### whatsapp.message.read

Triggered when the customer reads your message.

**When to use:**

* Track engagement rates
* Know when customers have seen important updates
* Follow up on unread messages

#### whatsapp.message.sent

Triggered when you successfully send a message.

**When to use:**

* Log all outgoing messages
* Track sent message count
* Backup message history

#### whatsapp.message.failed

Triggered when a message fails to send.

**When to use:**

* Alert your team about failed messages
* Retry sending automatically
* Investigate delivery issues

### Account & Business Events

#### whatsapp.account.alert

Important notifications about your WhatsApp Business account.

**Examples:**

* Account verification status changes
* Account restrictions or warnings
* Important compliance notifications

#### whatsapp.business.status_updated

Changes to your business account status.

**When to use:**

* Monitor account health
* Get notified about status changes
* Track account issues

### Template Events

#### whatsapp.template.status_updated

When your message templates are approved or rejected by WhatsApp.

**When to use:**

* Get notified when templates are approved
* Track rejected templates
* Monitor template submission status

#### whatsapp.template.quality_updated

When the quality rating of your template changes.

**When to use:**

* Monitor template performance
* Get alerts for low-quality templates
* Improve message quality

***

## Common Use Cases

### 1. Auto-Save Messages to Google Sheets

**Scenario:** Keep a backup of all customer conversations.

**Setup:**

1. Enable webhook forwarding
2. Select "Messages" event type
3. Connect to N8N/Zapier
4. Add Google Sheets action
5. Map fields: Customer Phone, Message, Timestamp

**Result:** Every message automatically appears in your spreadsheet.

***

### 2. Notify Team on Slack

**Scenario:** Alert your support team when customers message you.

**Setup:**

1. Forward "Messages Received" events
2. In N8N/Zapier, filter for specific keywords
3. Add Slack action
4. Post to your support channel

**Result:** Team gets instant Slack notifications for customer messages.

***

### 3. CRM Integration

**Scenario:** Update customer records when messages are sent/received.

**Setup:**

1. Forward message and status events
2. Use N8N to process the webhook
3. Look up customer in your CRM
4. Update last contact date, message count, etc.

**Result:** Your CRM stays automatically updated with WhatsApp activity.

***

### 4. Analytics Dashboard

**Scenario:** Track WhatsApp metrics in real-time.

**Setup:**

1. Forward all message events
2. Send to your analytics database
3. Calculate: message volume, response time, delivery rates

**Result:** Real-time WhatsApp performance dashboard.

***

### 5. Multi-Channel Support

**Scenario:** Route WhatsApp messages to your existing ticketing system.

**Setup:**

1. Forward "Messages Received" events
2. Use webhook to create ticket in your help desk
3. Include customer info and message content

**Result:** WhatsApp messages become support tickets automatically.

***

## Security

### Signature Verification

Every webhook includes a security signature to verify authenticity.

**How it works:**

1. We generate a unique signature for each webhook
2. The signature is sent in the `X-Webhook-Signature` header
3. Your endpoint can verify this signature
4. This prevents unauthorized/fake webhooks

**For developers:** See the [Advanced Section](#advanced-webhook-security) below for implementation details.

::: tip
When using N8N, Zapier, or Make.com, signature verification is handled automatically. You only need to implement this for custom endpoints.
:::

### Best Practices

**Do:**

* Use HTTPS URLs (not HTTP)
* Keep your webhook URL private
* Monitor webhook logs regularly
* Test with a few events before enabling all
* Implement signature verification for custom endpoints

**Don't:**

* Share your webhook URL publicly
* Use HTTP in production
* Forward more events than you need
* Ignore failed webhook notifications

***

## Troubleshooting

### Webhooks Not Arriving

**Problem:** Your endpoint isn't receiving webhooks.

**Solutions:**

1. **Check if forwarding is enabled**

   * Go to Settings → WhatsApp → Webhooks
   * Verify toggle is ON (green)

2. **Verify the URL**

   * Check for typos in the webhook URL
   * Make sure URL is accessible from the internet
   * Test the URL with a tool like Postman or curl

3. **Check event selection**

   * Ensure you've selected at least one event type
   * Verify the events you're waiting for are selected

4. **Test the endpoint**

   * Send a test message in WhatsApp
   * Check if webhook is triggered
   * Look for any error messages

5. **Check endpoint logs**
   * In N8N: Check execution logs
   * 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. **Verify event selection**

   * Go to webhook settings
   * Check which events are selected
   * Add missing event types

2. **Check event field mapping**
   * Different events have different field names
   * Ensure your selection includes the right fields

### Webhooks Timing Out

**Problem:** Webhooks fail with timeout errors.

**Solutions:**

1. **Optimize your endpoint**

   * Process webhooks quickly
   * Use background jobs for heavy processing
   * Return response immediately

2. **Check server resources**
   * Ensure your server isn't overloaded
   * Monitor response times

### Duplicate Webhooks

**Problem:** Receiving the same webhook multiple times.

**Solutions:**

* Our system prevents duplicates automatically
* If you still see duplicates, implement idempotency checks using the `event.id` field
* Store received event IDs and skip duplicates

***

## Testing Your Setup

### Step 1: Enable Webhook Forwarding

Make sure forwarding is enabled with a valid URL.

### Step 2: Select Test Events

Start with just "Messages" selected for simplicity.

### Step 3: Send a Test Message

1. Send a WhatsApp message to your connected number
2. Use a simple text message like "Test"

### Step 4: Check Your Endpoint

**For N8N:**

* Go to your workflow
* Check "Executions" tab
* You should see a new execution with the webhook data

**For Zapier:**

* Go to your Zap
* Check "Task History"
* Look for the latest task

**For Make.com:**

* Open your scenario
* Check execution history
* View the received data

### Step 5: Verify Data

Check that you received:

* Event type: `whatsapp.message.received`
* Message text: "Test"
* Sender phone number
* Timestamp

### Step 6: Add More Events

Once basic messages work, add other event types one at a time.

***

## Monitoring & Maintenance

### Regular Checks

**Weekly:**

* Review webhook success/failure rates
* Check for any error notifications
* Verify all expected events are forwarding

**Monthly:**

* Review which events you're using
* Disable unused event types
* Update webhook URLs if needed

### Performance Tips

1. **Be selective with events**

   * Only forward events you actually use
   * More events = more bandwidth

2. **Optimize your endpoint**

   * Return responses quickly
   * Process data asynchronously
   * Use queues for heavy tasks

3. **Monitor costs**
   * Some platforms charge per webhook execution
   * Only enable necessary events

***

## FAQ

### Q: How quickly are webhooks delivered?

**A:** Webhooks are sent in real-time, typically within 1-2 seconds of the WhatsApp event occurring.

### Q: What happens if my endpoint is down?

**A:** Currently, webhooks are sent once. If your endpoint is down, the webhook will fail. We recommend implementing retry logic on your end.

### Q: Can I forward to multiple URLs?

**A:** Currently, you can configure one webhook URL. If you need multiple destinations, use N8N or Zapier to fan out to multiple services.

### Q: Is there a webhook limit?

**A:** There's no artificial limit. You'll receive a webhook for every selected event type that occurs.

### Q: Can I test without sending real messages?

**A:** There's no built-in test feature currently. We recommend sending actual test messages to verify setup.

### Q: What if I change my webhook URL?

**A:** Simply update the URL in settings and save. All future webhooks will go to the new URL immediately.

### Q: Do webhooks work for all WhatsApp message types?

**A:** Yes! You'll receive webhooks for text, images, videos, documents, audio, locations, and all other WhatsApp message types.

### Q: Can I see webhook history?

**A:** Check your endpoint platform's logs:

* N8N: Executions tab
* Zapier: Task History
* Make.com: Execution History
* Custom: Check your server logs

### Q: Are webhooks included in my plan?

**A:** Webhook forwarding is included at no extra cost. However, destination platforms (N8N, Zapier) may have their own pricing.

### Q: Can I transform the data before forwarding?

**A:** The data is sent in a standardized format. Use N8N, Zapier, or Make.com to transform data after receiving it.

***

## Advanced: Developer Notes

::: warning For Developers
This section contains technical details for developers building custom integrations. If you're using N8N, Zapier, or Make.com, you can skip this section.
:::

### Webhook Signature Verification

All webhooks include an HMAC-SHA256 signature for verification.

**Headers sent with each webhook:**

```
X-Webhook-Signature: <hmac-sha256-hash>
X-Webhook-Event: whatsapp.message.received
X-Webhook-Timestamp: 2026-01-01T10:30:00Z
X-Webhook-Format: n8n
User-Agent: whatsmark-Webhook/1.0
Content-Type: application/json
```

**Verify signature in Node.js:**

```javascript
const crypto = require('crypto');

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

  // Use timing-safe comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// In your webhook handler
app.post('/webhook/whatsapp', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const secret = process.env.WEBHOOK_SECRET;

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

  // Process webhook...
  res.status(200).json({ received: true });
});
```

**Verify signature in PHP:**

```php
function verifyWebhookSignature($payload, $signature, $secret) {
    $expectedSignature = hash_hmac('sha256', json_encode($payload), $secret);
    return hash_equals($signature, $expectedSignature);
}

// In your webhook handler
$payload = json_decode(file_get_contents('php://input'), true);
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = getenv('WEBHOOK_SECRET');

if (!verifyWebhookSignature($payload, $signature, $secret)) {
    http_response_code(403);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// Process webhook...
```

**Verify signature in Python:**

```python
import hmac
import hashlib
import json

def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        json.dumps(payload).encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

# In your Flask webhook handler
@app.route('/webhook/whatsapp', methods=['POST'])
def webhook_handler():
    signature = request.headers.get('X-Webhook-Signature')
    secret = os.getenv('WEBHOOK_SECRET')

    if not verify_webhook_signature(request.json, signature, secret):
        return jsonify({'error': 'Invalid signature'}), 403

    # Process webhook...
    return jsonify({'received': True}), 200
```

::: tip Getting the Secret Key
Contact your system administrator or check your application configuration for the webhook signing secret. This is typically configured in your environment variables or configuration files.
:::

### Implementing Idempotency

To handle duplicate webhooks (network retries, etc.), implement idempotency:

```javascript
// Using Redis
const processedEvents = new Set();

async function handleWebhook(webhook) {
  const eventId = webhook.event.id;

  // Check if already processed
  if (await redis.get(`webhook:${eventId}`)) {
    console.log('Duplicate webhook, skipping');
    return;
  }

  // Process webhook
  await processWebhookData(webhook);

  // Mark as processed (expire after 24 hours)
  await redis.setex(`webhook:${eventId}`, 86400, '1');
}
```

### Event Type Reference

All possible event types you might receive:

```typescript
type WhatsAppEventType =
  // Message events
  | 'whatsapp.message.received'
  | 'whatsapp.message.sent'
  | 'whatsapp.message.delivered'
  | 'whatsapp.message.read'
  | 'whatsapp.message.failed'

  // Status events
  | 'whatsapp.status.updated'

  // Account events
  | 'whatsapp.account.alert'
  | 'whatsapp.account.review_updated'
  | 'whatsapp.account.updated'

  // Business events
  | 'whatsapp.business.capability_updated'
  | 'whatsapp.business.status_updated'

  // Template events
  | 'whatsapp.template.status_updated'
  | 'whatsapp.template.quality_updated'

  // Phone events
  | 'whatsapp.phone.quality_updated'
  | 'whatsapp.phone.name_updated'

  // Other events
  | 'whatsapp.call.received'
  | 'whatsapp.flow.event';
```

### Complete Payload Schema

```typescript
interface WebhookPayload {
  event: {
    id: string; // Unique event ID
    type: WhatsAppEventType; // Event type
    timestamp: string; // ISO 8601 timestamp
    version: string; // Format version (currently "1.0")
  };
  tenant: {
    id: number; // Tenant/account ID
    name: string; // Tenant/company name
  };
  data: {
    resource: {
      type: string; // Resource type (message, status, etc.)
      id: string | null; // Resource ID (message ID, etc.)
      attributes: Record<string, any>; // Resource-specific data
    };
    relationships: Record<string, any>; // Related entities
  };
  whatsapp: {
    original_payload: any; // Complete original WhatsApp payload
  };
  metadata: {
    source: 'whatsapp_webhook_forward';
    environment: string; // 'production', 'staging', etc.
    request_id: string; // Request trace ID
  };
}
```

### Rate Limiting Considerations

If you're receiving high volumes of webhooks:

1. **Use a queue system** (Redis, RabbitMQ, AWS SQS)
2. **Process asynchronously** - Don't block the webhook response
3. **Return 200 immediately** - Process in background
4. **Implement backpressure** - Throttle if overwhelmed

Example with queue:

```javascript
app.post('/webhook/whatsapp', async (req, res) => {
  // Verify signature
  if (!verifySignature(req.body, req.headers['x-webhook-signature'])) {
    return res.status(403).send('Invalid signature');
  }

  // Add to queue immediately
  await queue.add('whatsapp-webhook', req.body, {
    attempts: 3,
    backoff: {
      type: 'exponential',
      delay: 2000,
    },
  });

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

// Process queue separately
queue.process('whatsapp-webhook', async (job) => {
  const webhook = job.data;
  await processWebhook(webhook);
});
```

### Technical Documentation

For more technical details, see:

* [Complete Developer Documentation](./WHATSAPP_WEBHOOK_FORWARDING_FEATURE.md)
* [N8N Integration Guide](/products/whatsmark-saas/integrations/n8n-webhook-integration)
* [N8N Format Reference](/products/whatsmark-saas/integrations/webhook-format-reference)

***

## Support

Need help? Here's how to get support:

1. **Check this documentation** - Most questions are answered here
2. **Review the FAQ section** - Common issues and solutions
3. **Check platform documentation**:
   * [N8N Documentation](https://docs.n8n.io/)
   * [Zapier Help](https://help.zapier.com/)
   * [Make.com Help](https://www.make.com/en/help)
4. **Contact support** - Reach out to your account manager or support team

***

## Summary

Webhook forwarding is a powerful feature that connects your WhatsApp Business to the world of automation and integration. With just a few simple steps, you can:

* Automate customer responses
* Integrate with your existing tools
* Build custom workflows
* Track and analyze WhatsApp data
* Create seamless multi-channel experiences

Start with a simple integration (like saving messages to Google Sheets) and gradually build more complex automations as you get comfortable with the feature.

**Next Steps:**

1. Enable webhook forwarding in Settings
2. Choose an automation platform (N8N recommended)
3. Create your first simple workflow
4. Test with a few messages
5. Expand to more event types
6. Build more advanced automations

Happy automating!