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

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

Message processing that only reacts to delivered and read receipts:

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

Account and security monitoring:

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

Template management:

{
  "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:

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