whatsapp Trigger webhook icon

whatsapp Trigger webhook

Starts the workflow when a webhook is called
Join our community

Overview

This node acts as a webhook trigger for WhatsApp integrations in n8n. It listens for incoming HTTP GET and POST requests at a specified path, typically from the WhatsApp Business API (Meta). The node is designed to:

  • Validate webhook setup requests (GET) using a verification token.
  • Receive and process incoming WhatsApp messages or status updates (POST).
  • Optionally download and attach images sent via WhatsApp messages.
  • Route different types of events (validation, message, status update, invalid phone) to separate outputs.

Common scenarios:

  • Automating workflows based on incoming WhatsApp messages (e.g., customer support, notifications).
  • Handling media (images) sent by users via WhatsApp.
  • Integrating WhatsApp with CRM, ticketing, or notification systems.

Practical example:
A business can use this node to automatically respond to customer inquiries received on their WhatsApp number, log conversations, or trigger further automation based on message content.

Properties

Name Meaning
Path The URL path where the webhook will listen for incoming requests (e.g., webhook).
Verify Token A secret token used to verify webhook setup requests from Meta/WhatsApp.
Sender Phone Number (or ID) The ID of the business account's phone number from which messages are sent. Options are loaded dynamically from your WhatsApp Business Account.
Respond When and how to respond to the webhook. Options: "Immediately" (as soon as this node executes).
Response Code The HTTP response code returned to the sender (default: 200).
Response Data What data should be returned in the HTTP response. Options: All Entries, First Entry JSON, First Entry Binary, No Response Body.
Property Name Name of the binary property to return when "First Entry Binary" is selected for Response Data.

Output

The node has four output branches, each corresponding to a specific event type:

  1. Validate:

    • Triggered on webhook validation (GET request).
    • Output example:
      {
  "query": { /* query parameters from GET request */ }
}

  2. Message:

    • Triggered when a valid WhatsApp message is received (POST request, correct phone number).
    • If the message contains an image, the image is downloaded and attached as binary data.
    • Output example (text message):
      {
  "message": { /* full POST body from WhatsApp webhook */ }
}
    • Output example (image message):
      {
  "message": { /* full POST body */ },
  "binary": {
    "data": {
      "data": "<base64-encoded image>",
      "fileName": "image",
      "mimeType": "<MIME type>"
    }
  }
}

  3. status:

    • Triggered when a status update is received (e.g., message delivered/read).
    • Output example:
      {
  "updateMessage": { /* status change object from webhook */ }
}

  4. InvalidPhone:

    • Triggered if the incoming message's phone number does not match the configured one.
    • Output example:
      {
  "message": { /* full POST body */ }
}

Binary Output:
If the incoming WhatsApp message contains an image, the node downloads the image and attaches it as a base64-encoded binary property under binary.data.

Dependencies

  • External Service: WhatsApp Business API (Meta/Facebook)
  • API Credentials: Requires a WhatsApp API credential (whatsAppApi) with access token.
  • n8n Configuration:
    • Webhook URL must be accessible from Meta/WhatsApp servers.
    • The node must be activated in production mode for live traffic.
  • Environment: Internet access required for downloading media files.

Troubleshooting

Common Issues:

  • Webhook Not Triggering:

    • Ensure the webhook URL is correctly set up in the WhatsApp Business API dashboard.
    • Make sure the node is active and listening on the correct path.

  • Verification Fails ("Error token"):

    • The Verify Token provided in the node must match the one configured in the WhatsApp Business API settings.

  • Image Not Downloaded:

    • Check that the WhatsApp API credentials have permission to access media.
    • Ensure the server running n8n can reach WhatsApp's media URLs.

  • HTTP 401/403 Errors:

    • Invalid or expired access token in WhatsApp API credentials.

Error Messages:

  • "Error token": Indicates a mismatch between the provided and expected verification tokens during webhook setup.
    • Resolution: Double-check the Verify Token value in both n8n and WhatsApp Business API settings.

Links and References

Discussion