Webhook n8n không nhận request: checklist xử lý theo thứ tự

Bạn cài n8n lên VPS, mọi thứ chạy ngon lành, cho đến khi tích hợp webhook từ bên thứ ba gửi request về mà workflow không chạy. Kiểm tra thì thấy n8n vẫn sống, nhưng chẳng có execution nào được trigger. Lỗi này thường gặp khi tự host n8n, và nguyên nhân có thể nằm ở nhiều lớp khác nhau: từ DNS chưa trỏ đúng, firewall chặn, reverse proxy cấu hình sai, đến biến môi trường WEBHOOK_URL chưa khớp. Bài này mình sẽ hướng dẫn bạn một checklist xử lý có thứ tự, đi từ ngoài vào trong, để tìm ra chính xác lý do webhook n8n không chạy và fix nhanh nhất.

Tóm tắt nhanh

• Webhook n8n không chạy thường do 1 trong 5 nguyên nhân: DNS sai, firewall chặn cổng, reverse proxy cấu hình thiếu header, WEBHOOK_URL không khớp, hoặc workflow chưa active.
• Luôn kiểm tra theo thứ tự từ ngoài vào trong: DNS → firewall → reverse proxy → biến môi trường → workflow active → log n8n. Đừng nhảy thẳng vào log n8n.
• Câu lệnh curl -I https://n8n.domain.com/webhook-test/ten-webhook giúp bạn kiểm tra nhanh reverse proxy có pass request tới n8n hay không.
• Nếu dùng Docker Compose, WEBHOOK_URL phải trỏ đúng domain công khai, không phải localhost.

Yêu cầu trước khi bắt đầu

• VPS chạy Ubuntu 24.04 hoặc Debian 12, đã cài n8n bằng Docker Compose (theo hướng dẫn cài n8n trên Ubuntu 24.04).
• Quyền sudo hoặc root.
• Domain đã trỏ IP về VPS, có chứng chỉ SSL (dùng Certbot hoặc Caddy).
• Kiến thức cơ bản về DNS, firewall và reverse proxy.

Vì sao webhook n8n hay lỗi hơn các gọi API khác?

Webhook khác với gọi API thông thường ở chỗ: bên thứ ba (Zapier, Stripe, GitHub...) gửi request chủ động vào server của bạn mà không có quy trình bắt tay lại để kiểm tra kết nối trước. Một request thử (test) gửi vào /webhook-test/ có thể pass qua hết lớp trung gian nhưng lên tới n8n vẫn không match workflow nếu webhook ID sai hoặc workflow chưa active. Chưa kể, n8n chạy trong container với nhiều lớp mạng (host → Nginx → Docker bridge → n8n) nên sai một lớp là tắc toàn bộ. Do đó, cách riêng biệt để debug hiệu quả là kiểm tra từng lớp theo thứ tự, không đoán mò.

Bước 1 - Kiểm tra DNS

Mở terminal và chạy lệnh sau để kiểm tra domain của bạn có trỏ đúng IP VPS không:

dig +short n8n.domain.com
host n8n.domain.com

Kết quả phải là địa chỉ IPv4 của VPS bạn. Nếu ra IP khác hoặc không có record A, hãy cập nhật DNS zone của bạn. Đối với webhook, bạn cũng nên kiểm tra AAAA record nếu VPS có IPv6 (hầu hết VPS Việt Nam hiện nay cấp 1 IPv4 riêng, không có IPv6 mặc định, bạn cần xác nhận với nhà cung cấp).

VERIFY: Chạy nslookup n8n.domain.com rồi so sánh IP trả về với output của hostname -I trên VPS. Nếu khớp, DNS ổn.

Lưu ý: DNS propagation có thể mất vài giờ. Nếu bạn vừa trỏ domain, hãy dùng dig @8.8.8.8 n8n.domain.com để query trực tiếp từ DNS Google, bỏ qua cache local.

Bước 2 - Kiểm tra firewall

Firewall thường là thủ phạm hàng đầu khi webhook n8n không chạy. Request webhook thường gửi tới cổng 443 (HTTPS) hoặc 80 (HTTP). Kiểm tra xem cổng đó có mở không:

sudo ufw status verbose

Nếu dùng ufw, output phải có dòng 443/tcp ALLOW ANYWHERE. Nếu chưa, thêm rule:

sudo ufw allow 443/tcp
sudo ufw allow 80/tcp
sudo ufw reload

Nếu VPS của bạn dùng firewalld (AlmaLinux, Rocky Linux), lệnh kiểm tra là:

sudo firewall-cmd --list-all

VERIFY: Từ máy tính khác (không phải VPS), chạy nc -zv n8n.domain.com 443. Nếu thấy "open" hoặc "Connected", firewall không chặn. Nếu "Connection refused" thì firewall đang chặn hoặc service chưa listen.

Bước 3 - Kiểm tra reverse proxy (Nginx / Caddy)

Reverse proxy là lớp trung gian giữa internet và n8n. Nếu cấu hình thiếu header Host, X-Forwarded-For hoặc X-Forwarded-Proto, n8n không nhận diện được request gốc và webhook sẽ không được route đúng.

Kiểm tra cấu hình Nginx (file thường ở /etc/nginx/sites-available/n8n):

sudo nginx -t
sudo less /etc/nginx/sites-available/n8n

Đảm bảo block location / có các dòng sau:

proxy_pass http://localhost:5678;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

VERIFY: Gửi request test tới đúng endpoint webhook:

curl -I https://n8n.domain.com/webhook-test/ten-webhook-id

Output phải có HTTP/2 200 hoặc 301 (nếu chưa active webhook). Nếu ra 502 Bad Gateway hoặc 404, reverse proxy chưa pass request đúng tới n8n.

Nếu dùng Caddy, đảm bảo reverse proxy handle cả path /webhook/ và /webhook-test/. Caddy thường tự động handle SSL, nhưng cần bảo đảm tls internal không bị sai cấu hình.

Bước 4 - Kiểm tra biến môi trường WEBHOOK_URL

Đây là lỗi kinh điển khi self-host n8n. Nếu biến WEBHOOK_URL không được set hoặc set sai, n8n sẽ sinh webhook ID dựa trên địa chỉ internal (localhost) thay vì domain công khai, dẫn đến request từ bên ngoài không khớp.

Với Docker Compose, file docker-compose.yml của n8n thường có:

services:
  n8n:
    image: n8nio/n8n
    environment:
      - WEBHOOK_URL=https://n8n.domain.com

Kiểm tra xem biến này đã được set chưa:

docker exec -it <tên-container-n8n> env | grep WEBHOOK_URL

Nếu không có output, bạn cần thêm vào file docker-compose và restart container.

VERIFY: Sau khi set lại, truy cập vào web editor của n8n, mở workflow có webhook trigger, xem phần "Webhook URLs", phải hiển thị domain công khai, không phải localhost.

Bước 5 - Kiểm tra workflow có active và webhook đúng ID

Đôi khi vấn đề đơn giản hơn bạn nghĩ: workflow chưa được active. Trong n8n editor, mỗi workflow có nút "Active" ở góc trên bên phải. Nếu workflow chưa active, webhook không listen.

Kiểm tra nhanh qua API:

curl -s http://localhost:5678/rest/workflows | jq '.data[] | select(.name=="tên-workflow") | {id, active}'

Nếu active: false, bạn cần active workflow trong UI hoặc gọi API activate.

Một lỗi nữa: webhook ID trong URL mà bên thứ ba gửi request tới không khớp ID trong n8n. So sánh URL test trong workflow editor với URL bạn đang cấu hình ở bên thứ ba. Thường sai do copy thiếu ký tự hoặc nhầm /webhook/ với /webhook-test/.

Bước 6 - Kiểm tra log n8n

Nếu 5 bước trên đều ổn mà webhook n8n không chạy, hãy xem log real-time của n8n:

docker logs -f <tên-container-n8n>

Gửi một request webhook test từ bên thứ ba hoặc dùng curl:

curl -X POST https://n8n.domain.com/webhook-test/ten-webhook-id \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Trong log, bạn sẽ thấy một trong các trường hợp:

• Thành công: Dòng "Webhook got called" + execution ID. Workflow chạy.
• Không match: "No active workflow found for webhook", kiểm tra lại webhook ID hoặc workflow chưa active.
• Lỗi trùng webhook ID: "Webhook ID already in use", bạn có 2 workflow dùng cùng một webhook ID. Đổi ID cho workflow thứ hai.
• Lỗi kết nối database: "Error: getaddrinfo ENOTFOUND postgres", n8n không kết nối được database. Kiểm tra container database.

Nếu log không hiển thị gì khi gửi request, tức là request không tới được n8n, quay lại kiểm tra firewall và reverse proxy.

Xử lý lỗi thường gặp

Nếu sau tất cả vẫn không được, hãy kiểm tra rate limit từ bên thứ ba (một số service có giới hạn request gửi tới webhook, đặc biệt với free plan).

Câu hỏi thường gặp

Bài viết liên quan

• n8n queue mode với Redis: khi nào cần tách worker
• Chọn RAM cho n8n theo số workflow chạy song song
• Backup n8n đúng cách: encryption key, database và credential
• VPS là gì? So sánh VPS với hosting và dedicated server