WhatsApp trigger

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).

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 }}.

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

This tool receives WhatsApp Business events, such as incoming messages or status updates. It is ideal for initiating workflows based on real-time changes within a WhatsApp Business account, rather than sending messages or retrieving account information. The tool produces flattened event items, each detailing a specific change and its associated 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