On-Site Documentation

n8n Integration

Connect WhatsApp Gateway events to n8n workflows using an n8n Webhook node.

Download PDF Overview Quickstart Connect Instance Send Messages Receive Webhooks Responsible Messaging 3CX Overview 3CX Webhooks 3CX Call Events 3CX Troubleshooting n8n Integration Endpoint Map OpenAPI SDK Overview PHP Examples Node.js Examples Python Examples Postman Collection Troubleshooting

Workflow Automation

n8n Integration

WhatsApp Gateway sends selected normalized events to your n8n webhook URL. n8n receives events from WhatsApp Gateway and can route them into your internal workflows, CRMs, spreadsheets, and alerting tools.

WhatsApp Gateway manages message receiving automatically. n8n is for workflow automation, not marketing, cold outreach, spam, or bulk campaigns.

What You Can Build

Incoming WhatsApp message to email alert.
Incoming WhatsApp message to Google Sheets row.
Incoming WhatsApp message to CRM lead.

STOP / opt-out to update an opt-out list.
Message failed to notify an admin.
Message sent to update a tracking sheet.

Setup Steps

Create a new workflow in n8n.
Add a Webhook node.
Set the Webhook node method to POST.
Copy the Production URL from the Webhook node.
Go to WhatsApp Gateway → Integrations → n8n.
Paste the n8n Webhook URL.
Select the events your workflow should receive.
Generate a signing secret and store it in n8n if your workflow verifies signatures.
Send a test event, then activate the workflow in n8n.

Event Selection

Select only the events your workflow needs. Basic events cover common message flows; advanced events can be enabled for lifecycle, call, conversation, and group workflows.

message.received

recipient.opted_out

message.sent

message.failed

instance.connected

instance.disconnected

instance.connection_updated

instance.qr_updated

message.delivered

message.read

message.status_updated

conversation.updated

call.received

call.missed

group.message_received

group.updated

Webhook Security

When a signing secret is configured, WhatsApp Gateway signs each request so your workflow can verify the event body.

Header	Purpose
`X-WhatsApp-Gateway-Event`	Normalized event name.
`X-WhatsApp-Gateway-Timestamp`	Unix timestamp used for signature verification.
`X-WhatsApp-Gateway-Signature`	`sha256=<hmac_hex>` when a signing secret exists.

hmac_hex = HMAC_SHA256(timestamp + "." + raw_body, signing_secret)
signature_header = "sha256=" + hmac_hex

Example Payload

{
  "event": "message.received",
  "instance_id": "demo-support-line",
  "instance_name": "Demo Support Line",
  "from": "+9665XXXXXXX",
  "message_text": "Hello, I need help",
  "message_type": "text",
  "timestamp": "2026-05-09T10:00:00Z"
}

Workflow Templates

Starter templates use placeholder nodes and safe demo values. Replace placeholder credentials and destinations inside your private n8n workspace.

Email alert workflow

Incoming WhatsApp message to email alert.

Download JSON

Google Sheets workflow

Incoming WhatsApp message to Google Sheets row.

Download JSON

Opt-out workflow

recipient.opted_out to opt-out list placeholder.

Download JSON

Message failed alert workflow

message.failed to admin notification placeholder.

Download JSON

CRM HTTP request workflow

Incoming WhatsApp message to CRM HTTP request placeholder.

Download JSON

Troubleshooting

n8n webhook URL rejected: use a valid public HTTPS Production URL.
Private/internal URL blocked: use a public endpoint; localhost and private network URLs are blocked.
Test event failed: verify the workflow URL, activation state, and n8n network access.
Signature mismatch: verify the raw body, timestamp, and signing secret match exactly.

No event received: confirm the module is enabled, the integration is active, and the event is selected.
Module not enabled: ask an administrator to enable n8n for your account or plan.
Workflow not active: use the Production URL and activate the workflow.
Test URL vs Production URL: paste the Production URL into WhatsApp Gateway.