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 yourPHONE_NUMBER_IDfor outbound runtime sends - Your
WABA_IDfor 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_IDandPHONE_NUMBER_IDdirectly in your IF conditions or in an Edit Fields (Set) node. If your plan has custom Variables,$varsworks 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 withaccess to env vars denied, which turns the delivery into a500.
No
META_APP_SECRET? In the Embedded Signup flowX-Hub-Signature-256is 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.comand needs a Meta access token. Dualhook issues adh_live_...key instead.
Build the Webhook Workflow
Create one production workflow for your Meta callback path.
- Add a Webhook node.
- Keep the randomly generated Path. It is your main protection, see Keep the URL unguessable.
- In the node's Settings tab, turn on Allow Multiple HTTP Methods. Back in Parameters, keep
GETandPOST. The node now has one output per method. - Set Respond to Using 'Respond to Webhook' Node.
- 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.bodyeither way. - 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:
GEToutput for Meta verificationPOSToutput for inbound payload validation and event processing
Handle the Verification Handshake
Meta verifies your callback URL with a GET request that includes:
hub.mode=subscribehub.verify_token=<YOUR_VERIFY_TOKEN>hub.challenge=<CHALLENGE_VALUE>
In the GET output, add an IF node with two conditions:
{{ $json.query['hub.mode'] }}equalssubscribe{{ $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 withContent-Type: text/plain, because n8n's Text response defaults totext/html. - False: set Respond With to Text, Response Body to
Forbidden, and under Options set Response Code to403.
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 }}equalswhatsapp_business_account{{ $json.body.entry[0].id }}equals yourWABA_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 yourPHONE_NUMBER_ID
The same URL receives two kinds of fields:
- Message-path fields, sent by Meta directly:
messages(inbound messages andstatuses), plussmb_message_echoes,historyandsmb_app_state_syncon Coexistence numbers. All four carryvalue.metadata.phone_number_id. - Management fields such as
message_template_status_updateoraccount_update, forwarded by Dualhook with anX-Dualhook-Eventheader and noX-Hub-Signature-256. They have nometadata.phone_number_id, so checkentry[0].idonly. 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
historysync in chunks, often hundreds of events and up to 3 MB each. Answer every chunk with200, 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:
- Return
200as soon as the envelope check passes. - 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
- Publish the n8n workflow so the Production URL is active.
- Put that Production URL in Dualhook as the webhook URL.
- Use the same verify token in Dualhook and in your n8n verification branch.
- Run Dualhook Test endpoint to confirm reachability.
- Send a real WhatsApp message to your number.
- 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
messagesarray andX-Dualhook-Event: test_ping) - the workflow returns
200quickly - both inbound messages and
statusesevents are handled - on Coexistence, a reply sent from the WhatsApp Business app arrives as
smb_message_echoesand 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=noneon 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
wamidand 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
404and Meta deliveries fail until you publish it again. - If the workflow runs an AI agent, route on
fieldfirst, so a staff reply insmb_message_echoesis 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.