<!-- BusyBot node reference — https://busybot.net/tools/whatsapp-trigger/ -->

> Node: WhatsApp Trigger (`whatsapp_trigger`) · Webhook trigger · v1
> Category: Communication · Credentials: WhatsApp Business (Trigger) (`whatsAppTriggerApi`)
> Updated: 2026-08-16

# WhatsApp Trigger

> Listen for WhatsApp Business webhook events

## Overview

Starts a workflow when the WhatsApp Business Cloud API sends webhook notifications. Supports subscribing to incoming messages, message delivery status updates, account review updates, account updates, business capability updates, message template quality/status updates, phone number name/quality updates, security events, and template category updates. Uses Facebook platform webhook verification (GET challenge/response) and validates HMAC-SHA256 signatures via the x-hub-signature-256 header using the Facebook App Secret. Each webhook payload contains an entry array with changes that are flattened into individual event items. Optionally filters message status update events (sent, delivered, read, failed, deleted).

**Category:** Communication  
**Tool Name:** `whatsapp_trigger`  
**Version:** 1

**Appearance:** Icon: `si-whatsapp` | Color: `#25d366`

## Node Type

**Trigger** — webhook (receives incoming HTTP callbacks)

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | None (trigger node) |
| Output | `Output` |

## Credentials

This tool requires **WhatsApp Business (Trigger)** credentials.
See the [Credentials Guide](https://busybot.net/credentials/whats-app-trigger-api/) for setup instructions.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Trigger On | `multiOptions` | Yes | `[]` | Which WhatsApp Business events to listen for. |
| | | | | Options: `account_review_update`, `account_update`, `business_capability_update`, `message_template_quality_update`, `message_template_status_update`, `messages`, `phone_number_name_update`, `phone_number_quality_update`, `security`, `template_category_update` |
| Options | `collection` | No | `{}` | Additional options for the trigger. |
| — Receive Message Status Updates | `multiOptions` | No | `["all"]` | WhatsApp sends notifications when the status of a message changes (e.g. from Sent to Delivered, from Delivered to Read). To avoid multiple executions for one WhatsApp message, set the trigger to execute only on selected message status updates. |
| | | | | Options: `all`, `deleted`, `delivered`, `failed`, `read`, `sent` |

## Output Data

A WhatsApp delivery carries an `entry` array whose `changes` are flattened, so **one POST can produce several output items** — one per change that survives filtering.

Each item contains the change's `value` object spread at the top level, plus:

- `field` — the subscription field the change belongs to, e.g. `messages`
- `_trigger` — always `whatsapp_webhook`
- `_timestamp` — ISO 8601 timestamp of when the delivery was received
- `_webhookEvent` — the same value as `field`, or `unknown` when WhatsApp omitted it

For `messages` changes the `value` object carries the usual WhatsApp Cloud API structure: `messaging_product`, `metadata`, `contacts`, and either `messages` or `statuses`.

Status-change notifications are filtered by **Receive Message Status Updates**; when nothing survives, the delivery is acknowledged without starting the workflow. Deliveries whose `object` is not `whatsapp_business_account` are ignored, and Facebook's `hub.challenge` verification request is answered automatically without starting the workflow.

Reference the payload downstream by expression, e.g. `{{ $json.messages[0].text.body }}`.

## Usage Examples

- trigger workflow when a WhatsApp message is received
- listen for WhatsApp message delivery status updates
- start workflow on WhatsApp account review update
- receive WhatsApp template status change notifications
- monitor WhatsApp phone number quality updates

## Example Configuration

Incoming messages with all status updates:

```json
{
  "type": "whatsapp_trigger",
  "parameters": {
    "updates": ["messages"],
    "options": {
      "messageStatusUpdates": ["all"]
    }
  }
}
```

Message processing that only reacts to delivered and read receipts:

```json
{
  "type": "whatsapp_trigger",
  "parameters": {
    "updates": ["messages"],
    "options": {
      "messageStatusUpdates": ["delivered", "read"]
    }
  }
}
```

Account and security monitoring:

```json
{
  "type": "whatsapp_trigger",
  "parameters": {
    "updates": ["account_update", "account_review_update", "security"]
  }
}
```

Template management:

```json
{
  "type": "whatsapp_trigger",
  "parameters": {
    "updates": [
      "message_template_status_update",
      "message_template_quality_update",
      "template_category_update"
    ]
  }
}
```

Business capability and phone number monitoring, alerting only on failures:

```json
{
  "type": "whatsapp_trigger",
  "parameters": {
    "updates": [
      "business_capability_update",
      "phone_number_quality_update",
      "phone_number_name_update"
    ],
    "options": {
      "messageStatusUpdates": ["failed"]
    }
  }
}
```

### Trigger Behavior

- **Activation:** When the workflow is activated, a webhook endpoint is registered with the service.
- **Deactivation:** The webhook is automatically unregistered when the workflow is deactivated.
- **Payload:** The incoming webhook payload is parsed and output as workflow items.
- **Verification:** Supports signature verification where applicable.

## Tips

Entry point that fires when WhatsApp Business Cloud API sends a webhook notification for subscribed events. Configure your Facebook App credentials (Client ID and Secret) and select which event types to subscribe to (messages, status updates, account changes, etc.). Optionally filter message status updates to avoid multiple executions per message. Outputs flattened change events, each containing the field name and its value data.

### Important Notes

- Due to Facebook API limitations, you can use just one WhatsApp trigger for each Facebook App
- The `updates` parameter is required and must contain at least one event type
- When using message-related triggers, configure `messageStatusUpdates` in the `options` to control execution frequency
- The `options` parameter fields must be nested directly under the `"options"` key