Introduction
n8n WhatsApp integration unlocks conversational automation for notifications, lead routing, and two-way customer messaging. In my projects building customer support automations, I’ve used the WhatsApp Cloud API with self-hosted n8n workflows to reliably route leads into CRMs, send order updates, and handle inbound messages at scale. This post walks through a practical, step-by-step n8n WhatsApp integration using the Webhook and HTTP Request nodes, shows real node settings and code snippets, and covers error handling and best practices.
Prerequisites
- An n8n instance (cloud or self-hosted). In my experience, self-hosted n8n workflows are easier to secure when dealing with message webhooks.
- WhatsApp Business Cloud API access (Meta Business account) and a phone_number_id + access token.
- A public HTTPS endpoint for WhatsApp webhooks (use n8n’s Webhook node with a public URL or ngrok for local testing).
- Basic familiarity with n8n nodes: Webhook, HTTP Request, Function/Code, Set, and Wait nodes.
- Optional: a CRM (HubSpot, Pipedrive) for lead routing demonstrations.
Architecture overview
1. WhatsApp sends inbound message webhooks to n8n’s Webhook node.
2. n8n verifies webhook signature (security best practice).
3. Workflow parses the incoming message, looks up or creates a contact, and routes to the CRM.
4. n8n sends outbound messages back through WhatsApp Cloud API with the HTTP Request node.
This architecture gives you a two-way conversational loop with visibility and error handling.
Step-by-step guide
1. Create credentials and store secrets
1. In n8n, store the WhatsApp API token as a credential in the Credentials section or use environment variables for self-hosted instances: `WHATSAPP_ACCESS_TOKEN` and `WHATSAPP_PHONE_ID`.
2. Keep your App Secret for webhook signature verification as `WHATSAPP_APP_SECRET`.
2. Create the Webhook node
1. Add a Webhook node to the workflow.
2. Set HTTP Method = POST, Response Mode = On Received (or Immediately if you want instant 200). Choose a path like `/whatsapp-inbound`.
3. Save and copy the webhook URL. Use it in the WhatsApp Cloud API webhook settings in Meta Business Manager.
3. Verify webhook payloads (Function node)
1. Insert a Function node immediately after the Webhook to verify `X-Hub-Signature-256`.
2. Example verification JavaScript (in a Code node):
javascript
// Use this in an n8n Function node
const crypto = require('crypto');
const secret = process.env.WHATSAPP_APP_SECRET || $credentials.whatsappAppSecret;
const signature = $json["headers"]["x-hub-signature-256"] || $json["headers"]["X-Hub-Signature-256"] || '';
const rawBody = $binary.toString(); // n8n provides raw body in binary output if available
const hash = `sha256=${crypto.createHmac('sha256', secret).update(rawBody).digest('hex')}`;
if (signature !== hash) {
throw new Error('Invalid WhatsApp webhook signature');
}
return items;
Note: If your Webhook node doesn’t provide raw binary automatically, set Webhook response to pass-through and use the body JSON for lighter validation—though raw signature validation is best.
4. Parse inbound messages
1. Use a Set node to map fields: phone number, message id, text, timestamp.
2. Example mapping expressions:
– from: `{{$json[“entry”][0].changes[0].value.messages[0].from}}`
– text: `{{$json[“entry”][0].changes[0].value.messages[0].text.body}}`
5. Look up or create contact (HTTP Request / CRM node)
1. Use the CRM node or HTTP Request to query your CRM by phone.
2. If not found, create a contact and tag source = “WhatsApp”.
6. Send outbound messages via HTTP Request
1. Add an HTTP Request node configured like this:
– HTTP Method: POST
– URL: `https://graph.facebook.com/v17.0/{{ $env.WHATSAPP_PHONE_ID }}/messages` or `https://graph.facebook.com/v17.0/
– Authentication: Header with `Authorization: Bearer
– Content-Type: application/json
– Body (raw JSON) example:
json
{
"messaging_product": "whatsapp",
"to": "{{ $json["to"] }}",
"type": "text",
"text": {"body": "Hello {{ $json["contactName"] || "there" }}, we received your message and will reply shortly."}
}
2. Save and test sending messages. Watch the HTTP Request response for `messages[0].id` which you can log.
7. Add retries and backoff
1. For transient HTTP 429 or 5xx responses, add an Error Trigger node or configure the HTTP Request node to retry with exponential backoff using a Wait node in a retry loop.
2. Example pattern: On error, Route to a Wait node (30s -> 2m -> 5m) and retry up to 3 times.
8. Deploy and monitor
1. If self-hosted, ensure your n8n instance is behind HTTPS and keeps env vars secure.
2. Log inbound/outbound messages to a database for monitoring and auditing.
Real n8n node settings (practical tips)
Best practices
Common pitfalls & fixes
– Fix: Ensure you validate the raw request body for HMAC; if testing with ngrok, confirm the payload is unmodified and the `WHATSAPP_APP_SECRET` is correct.
– Fix: Check phone number formatting (E.164), ensure `messaging_product` = “whatsapp”, and confirm your phone_number_id is correct.
– Fix: Implement retry loop with exponential backoff and store message state; use idempotency keys.
– Fix: Batch outbound sends and throttle using Wait + SplitInBatches nodes.
FAQ
How do I test WhatsApp webhooks locally with n8n?
Use ngrok to expose your local n8n webhook URL and register the ngrok HTTPS URL in Meta Business Manager. Remember ngrok changes URLs unless you have a paid reserved domain—update the webhook config accordingly.
Can I use n8n Credentials vs environment variables?
Yes. For cloud n8n, credentials are convenient. For self-hosted, environment variables are safer for CI/CD and secret rotation. In my deployments, I keep production tokens in environment variables and use n8n credentials only for ephemeral tests.
How do I handle media messages?
WhatsApp webhooks include `messages[0].type` (image, document, audio). Use the HTTP Request node to download media URLs (requires Authorization header) and process or store them in S3.
What about two-way interactive messages and templates?
Use the HTTP Request node with template message payloads and the `interactive` type for buttons. Ensure templates are approved in Meta Business Manager before sending template messages.
How do I scale this workflow?
Scale by running multiple n8n workers with a shared Redis or queue for job coordination, and shard message sending per phone_number_id. Add backpressure with database-backed queues for very high throughput.
Conclusion
n8n WhatsApp integration provides powerful two-way automation for support, notifications, and lead routing. In my projects, a small set of nodes (Webhook, Function, HTTP Request, CRM nodes, and Wait) plus careful signature verification and retry logic has produced reliable, auditable conversational automations. Try this in your n8n instance today: set up the Webhook, verify signatures, map inbound fields, and use the HTTP Request node to send messages. For related reading, see our guide on [n8n Fundamentals](/fundamentals) and the practical tips on building resilient connectors.
Next steps: deploy with secure env vars, add monitoring for failed sends, and extend the workflow to support media and interactive templates.