n8n WhatsApp Webhook Setup

Step-by-step n8n workflow for a Dualhook connection: Meta's GET verification, payload validation, skipping status executions, and template sends.

This guide builds the n8n workflow for a Dualhook connection, step by step. Settings were tested on n8n 2.46.6 on 6 November 2026. Still choosing how to connect WhatsApp to n8n, or comparing prices? See the best WhatsApp API for n8n, which also covers when you do not need Dualhook.

Prerequisites

  • An n8n Cloud or self-hosted instance with a workflow you can publish
  • A Dualhook connection in progress or active. Dualhook asks for your webhook URL and verify token before Meta's signup opens, so build the workflow first
  • A verify token you choose, used only for the GET handshake
  • A per-connection Dualhook dh_live_... key and your PHONE_NUMBER_ID for outbound runtime sends
  • Your WABA_ID for payload-side validation

Where to keep these values in n8n:

  • Put the dh_live_... key in an n8n Bearer Auth credential, not in a node field.
  • Put the verify token, WABA_ID and PHONE_NUMBER_ID directly in your IF conditions or in an Edit Fields (Set) node. If your plan has custom Variables, $vars works too. They are not available on self-hosted Community Edition or n8n Cloud Starter.
  • Do not use $env. Since n8n 2.0 it is blocked by default, and the expression fails with access to env vars denied, which turns the delivery into a 500.

No META_APP_SECRET? In the Embedded Signup flow X-Hub-Signature-256 is signed by Dualhook's Meta app and isn't customer-verifiable: validate inbound webhook payload shape instead. These checks do not prove the sender is Meta, so treat the URL as a secret. See Messaging Webhook → Inbound Webhook POST Validation.

Architecture Overview

With Dualhook, Meta sends message-path webhooks directly to your n8n webhook URL. Dualhook stays out of the message content path and focuses on setup, monitoring, and management events.

Meta (messages, statuses, errors; Coexistence echoes, history, contacts)
  → n8n Webhook URL
     → verification
     → inbound payload validation
     → business workflow
     → optional send through api.dualhook.com

Dualhook
  → management events, health visibility, template operations

n8n becomes part of your message-processing boundary. If you keep execution history, pinned data, or verbose logs enabled, message content can be retained in n8n even though Dualhook itself does not store it. See Compliance & Data Retention and Architecture & Security for the privacy split.

Which n8n Nodes to Use

On a Dualhook connection, receive with the Webhook node and send with the HTTP Request node. n8n's native WhatsApp nodes are built for your own Meta app and do not work here:

  • WhatsApp Trigger checks each delivery's signature against the app secret in your credential. Meta signs with Dualhook's app, so the node drops the delivery without an error or an execution. Its event list also has no Coexistence fields.
  • WhatsApp Business Cloud is fixed to graph.facebook.com and needs a Meta access token. Dualhook issues a dh_live_... key instead.

Build the Webhook Workflow

Create one production workflow for your Meta callback path.

  1. Add a Webhook node.
  2. Keep the randomly generated Path. It is your main protection, see Keep the URL unguessable.
  3. In the node's Settings tab, turn on Allow Multiple HTTP Methods. Back in Parameters, keep GET and POST. The node now has one output per method.
  4. Set Respond to Using 'Respond to Webhook' Node.
  5. Leave the Raw Body option off. It exists for signature checks you cannot do on a Dualhook connection, and it saves a second copy of every payload as binary data in the execution. The parsed payload is at $json.body either way.
  6. Publish the workflow and use the Production URL (/webhook/...) in Dualhook.

Do not use the Test URL (/webhook-test/...) for real traffic: it only answers one call after you click Execute workflow, then returns 404.

The simplest branch layout is:

  • GET output for Meta verification
  • POST output for inbound payload validation and event processing

Handle the Verification Handshake

Meta verifies your callback URL with a GET request that includes:

  • hub.mode=subscribe
  • hub.verify_token=<YOUR_VERIFY_TOKEN>
  • hub.challenge=<CHALLENGE_VALUE>

In the GET output, add an IF node with two conditions:

  • {{ $json.query['hub.mode'] }} equals subscribe
  • {{ $json.query['hub.verify_token'] }} equals your verify token

Then add one Respond to Webhook node to each IF output:

  • True: set Respond With to Text and Response Body to {{ $json.query['hub.challenge'] }}. Under Options, add Response Headers with Content-Type: text/plain, because n8n's Text response defaults to text/html.
  • False: set Respond With to Text, Response Body to Forbidden, and under Options set Response Code to 403.

Do not respond with JSON: Meta needs the raw challenge as the body, and Dualhook's setup check reports a JSON-wrapped challenge as a failure.

Keep the verify token check on the GET output only. Real deliveries are POST requests with no hub.verify_token, so a token check on them drops every message.

Dualhook uses the same verify token you entered during connection setup, so the value in n8n and the value stored on the Dualhook connection must match.

Validate the Webhook Payload

Validate every POST before you process the payload. Confirm the WhatsApp envelope shape and the WABA ID / phone_number_id against the values you stored for this connection.

Check the envelope, WABA, and phone number

In the POST output, add an IF (or Code) node that checks the envelope first and the field-specific identity second. n8n puts the request payload under body:

  • {{ $json.body.object }} equals whatsapp_business_account
  • {{ $json.body.entry[0].id }} equals your WABA_ID
  • Read {{ $json.body.entry[0].changes[0].field }} and route on it (see below)
  • For message-path fields, {{ $json.body.entry[0].changes[0].value.metadata.phone_number_id }} is present and equals your PHONE_NUMBER_ID

The same URL receives two kinds of fields:

  • Message-path fields, sent by Meta directly: messages (inbound messages and statuses), plus smb_message_echoes, history and smb_app_state_sync on Coexistence numbers. All four carry value.metadata.phone_number_id.
  • Management fields such as message_template_status_update or account_update, forwarded by Dualhook with an X-Dualhook-Event header and no X-Hub-Signature-256. They have no metadata.phone_number_id, so check entry[0].id only. See Forwarding Headers.

If the envelope or an ID check fails, respond 401 with a Respond to Webhook node and stop the workflow. A field your workflow does not process is not a failure: return 200 and skip it. Meta retries a rejected message-path delivery for up to 7 days, while a rejected management event is lost, because Dualhook forwards each one once.

Coexistence history sync: right after onboarding, Meta sends the one-time history sync in chunks, often hundreds of events and up to 3 MB each. Answer every chunk with 200, even ones you discard. A rejected chunk cannot be requested again once Meta's retries end; the only way to rerun the sync is a full re-onboard. n8n's own webhook limit is 16 MB, but if self-hosted n8n sits behind a reverse proxy, set its request body limit above 3 MB (nginx defaults to 1 MB). See History Webhook.

Keep the URL unguessable

Use n8n's randomly generated webhook path. Treat that path as a secret: do not paste it into shared chat, do not commit it to repos, and rotate it (publish the workflow to a new path, then update the URL in Dualhook) if it leaks. The payload checks above stop stray and casual requests, but anyone who learns your URL and IDs could send a matching payload, so do not let a webhook alone trigger anything irreversible.

Respond early

For valid payloads:

  1. Return 200 as soon as the envelope check passes.
  2. Continue the heavy work after the response step.

For payloads that fail validation:

  • Return 401
  • Stop processing

This keeps webhook acknowledgments fast enough for Meta retries to stay rare. n8n sends the response as soon as the Respond to Webhook node runs, and any nodes after it keep running.

Skip Status Executions

n8n Cloud plans count executions, and every webhook that starts your workflow is one. A message you send can return sent, delivered and read status webhooks on top of the inbound traffic. Since n8n 2.28 the Webhook node can answer those with 200 and create no execution.

In the Webhook node, under Options, add Only Run If and set it to this expression:

{{ !$json.body.entry || $json.body.entry.flatMap(e => e.changes).some(c => !c.value?.statuses || c.value.statuses.some(s => s.status === 'failed')) }}

In our test this skipped sent, delivered and read, and ran the workflow for the GET handshake, inbound messages, failed statuses, a mixed batch, smb_message_echoes, history and a template management event. Keep failed as it is here: a send can return 200 and only report its error in that status.

Two cautions. The expression must let GET through, because a skipped GET answers {"message":"Webhook call received"} and Meta's verification fails. And leave this option off if your workflow needs delivery or read receipts.

Send Template Messages via Dualhook

n8n sends outbound messages through Dualhook's allowlisted runtime. Inbound routing remains direct from Meta.

Use an HTTP Request node with a Bearer Auth credential:

  • Method: POST
  • URL: https://api.dualhook.com/v25.0/<PHONE_NUMBER_ID>/messages
  • Authentication: Generic Credential Type, then Bearer Auth, with your dh_live_... key as the token
  • Send Body: on, Body Content Type JSON, Specify Body Using JSON

Example template send:

{
  "messaging_product": "whatsapp",
  "to": "12015550123",
  "type": "template",
  "template": {
    "name": "order_update_v1",
    "language": { "code": "en_US" }
  }
}

For variables, media headers, and button parameters, see Sending Template Messages.

Test with Dualhook

  1. Publish the n8n workflow so the Production URL is active.
  2. Put that Production URL in Dualhook as the webhook URL.
  3. Use the same verify token in Dualhook and in your n8n verification branch.
  4. Run Dualhook Test endpoint to confirm reachability.
  5. Send a real WhatsApp message to your number.
  6. Confirm that:
    • verification succeeds
    • inbound payload validation accepts the real Meta POST and the sample event from Test endpoint (a Meta-shaped envelope with your WABA and phone number ID, an empty messages array and X-Dualhook-Event: test_ping)
    • the workflow returns 200 quickly
    • both inbound messages and statuses events are handled
    • on Coexistence, a reply sent from the WhatsApp Business app arrives as smb_message_echoes and is accepted, while a send from your own workflow does not echo

Production Caveats

  • n8n saves execution data by default, including message text. To preserve Dualhook's minimal-storage posture downstream, set Save successful production executions to Do not save in the workflow settings, or EXECUTIONS_DATA_SAVE_ON_SUCCESS=none on a self-hosted instance. Also review pinned data and logs.
  • Use n8n credentials instead of pasting secrets into node fields. In self-hosted production, set N8N_ENCRYPTION_KEY. If you run n8n Enterprise, external secrets are worth considering.
  • Use idempotency in downstream processing. A practical pattern is deduping inbound messages on wamid and statuses on (message_id, status).
  • Treat WhatsApp webhook payloads as evolving. With Meta's BSUID rollout and later username launch, some fields are conditional. Parse defensively and prefer field presence checks over rigid assumptions. See the BSUID webhook changes reference.
  • If you unpublish the workflow, the Production URL returns 404 and Meta deliveries fail until you publish it again.
  • If the workflow runs an AI agent, route on field first, so a staff reply in smb_message_echoes is not treated as a customer message. Keep the agent about your own business and give customers a way to reach a person: Meta's terms restrict general-purpose AI assistants, and its policy requires escalation paths when you automate replies. See AI agents on WhatsApp Business.

Related

Browse more docsStart Free Trial