Hướng dẫn cài đặt ngrok và tích hợp n8n trên localhost A-Z

ngrok tạo một địa chỉ HTTPS công khai chuyển tiếp về n8n đang chạy ở localhost:5678, nhờ đó dịch vụ bên ngoài gửi được webhook vào máy tính của bạn. Cách làm: cài ngrok, thêm authtoken, chạy ngrok http 5678, đặt N8N_WEBHOOK_URL bằng địa chỉ ngrok rồi khởi động lại n8n. Chỉ dùng để thử, không dùng cho production.

Bài này dành cho n8n chạy trên máy tính cá nhân; nếu chưa cài, xem cách cài đặt n8n trên máy tính PC bằng Docker Desktop. Khi cần chạy workflow 24/7, chuyển sang cài đặt n8n trên VPS.

Tại sao cần sử dụng ngrok với n8n?

Vấn đề của việc phát triển n8n trên môi trường localhost

n8n chạy trên máy tính cá nhân có địa chỉ mặc định http://localhost:5678. Địa chỉ localhost chỉ có ý nghĩa bên trong máy của bạn, giống số điện thoại nội bộ: người trong văn phòng gọi được, người bên ngoài thì không. Vấn đề lộ rõ nhất khi bạn làm việc với webhook.

Webhook là cơ chế dịch vụ bên ngoài chủ động gửi dữ liệu đến n8n ngay khi có sự kiện (đơn hàng mới, tin nhắn mới, dòng mới trong trang tính…). Để làm được, dịch vụ đó cần một URL công khai truy cập được từ Internet; cách node Webhook hoạt động xem ở node Webhook trong n8n. Dịch vụ bên ngoài không gửi được dữ liệu đến http://localhost:5678, nên:

• Bạn không nhận được dữ liệu webhook thật để kiểm tra workflow có chạy đúng không.
• Bạn phải đoán cấu trúc dữ liệu, hoặc đưa workflow lên máy chủ công khai chỉ để thử một thay đổi nhỏ.
• Không có dữ liệu thật, việc tìm và sửa lỗi trong logic workflow khó hơn nhiều.

ngrok là gì? Giải quyết vấn đề này như thế nào?

ngrok là công cụ tạo “đường hầm” (tunnel): nó cấp một URL công khai và chuyển toàn bộ yêu cầu gửi đến URL đó về một cổng trên máy của bạn, ở đây là cổng 5678 của n8n. Bạn đưa URL này cho dịch vụ bên ngoài (Shopify, GitHub, Telegram…), và mọi dữ liệu họ gửi sẽ đi thẳng vào n8n trên máy tính.

Tài khoản ngrok Free được cấp một dev domain cố định dạng ten-ngau-nhien.ngrok-free.dev, gắn với tài khoản, nên URL không đổi mỗi lần chạy lại (ngrok pricing, 23/10/2026).

Từ n8n 2.0, lệnh tunnel có sẵn n8n start --tunnel đã bị gỡ (v2.0 breaking changes); để thử webhook trên máy, dùng ngrok, localtunnel hoặc Cloudflare Tunnel.

Lợi ích chính khi kết hợp n8n và ngrok

• Kiểm thử và gỡ lỗi theo thời gian thực: tạo một sự kiện thật (ví dụ đơn hàng thử trên Shopify) và thấy ngay dữ liệu chảy vào workflow trên máy, nhờ đó hiểu đúng cấu trúc dữ liệu.
• Thử webhook nhanh hơn: sửa, lưu và thử workflow ngay trên máy thay vì triển khai lên máy chủ mỗi lần thay đổi.
• Chưa cần thuê máy chủ: giai đoạn phát triển và thử nghiệm có thể làm hết trên máy tính; khi chạy thật mới cần VPS.
• Dễ demo: chạy n8n và ngrok trên laptop là có bản demo trực tiếp cho khách hàng, đồng nghiệp.
• Giao diện giám sát: ngrok có trang http://127.0.0.1:4040 để xem và phát lại (replay) các request đã đi qua đường hầm.

Hướng dẫn cài đặt ngrok và tích hợp n8n trên localhost

Chuẩn bị

• n8n chạy trên máy tính: xem hướng dẫn cài n8n trên máy tính bằng Docker Desktop.
• Tài khoản ngrok (gói Free là đủ): cần để lấy authtoken. Đăng ký tại ngrok.com.
• Cửa sổ dòng lệnh: PowerShell hoặc Command Prompt trên Windows; Terminal trên macOS, Linux.

Hướng dẫn cài đặt ngrok

Bước 1: Đăng nhập dashboard của ngrok. Ở mục Setup & Installation, ngrok tự nhận diện hệ điều hành. Chọn tab Download rồi tải file .zip phù hợp (ví dụ Windows 64-bit).

Bước 2: Giải nén file .zip, bạn nhận được một file duy nhất là ngrok.exe (Windows) hoặc ngrok (macOS, Linux).

Để gọi lệnh ngrok từ bất kỳ thư mục nào, đưa file vào thư mục hệ thống:

• macOS, Linux: chạy sudo mv /path/to/ngrok /usr/local/bin/.
• Windows: tạo thư mục, ví dụ C:\ngrok, chép ngrok.exe vào đó rồi thêm C:\ngrok vào biến môi trường Path. Cách khác: cài từ Microsoft Store như ngrok gợi ý.

Bước 3: Gắn ngrok với tài khoản của bạn bằng authtoken. Trên dashboard, sao chép dòng lệnh có dạng:

ngrok config add-authtoken <YOUR_AUTH_TOKEN>

Authtoken là mật khẩu của tài khoản ngrok: không chia sẻ, không đưa vào ảnh chụp màn hình. Nếu lỡ lộ, tạo lại token trong dashboard.

Bước 4: Mở PowerShell hoặc Terminal, dán dòng lệnh vừa sao chép rồi nhấn Enter.

Thông báo Authtoken saved to configuration file xuất hiện là ngrok đã sẵn sàng.

Cách tích hợp ngrok với n8n để nhận webhook

Tích hợp ngrok với n8n gồm ba việc: mở đường hầm tới cổng 5678, khai báo địa chỉ ngrok cho n8n qua N8N_WEBHOOK_URL, rồi khởi động lại n8n để node Webhook hiện đúng URL công khai.

Bước 1: Mở n8n và đảm bảo n8n đang chạy ở cổng 5678.

Bước 2: Trong cửa sổ dòng lệnh, chạy:

ngrok http 5678

Lệnh này tạo đường hầm HTTPS công khai và chuyển mọi truy cập đến cổng 5678 trên máy của bạn.

Bước 3: Trong giao diện ngrok hiện ra, tìm dòng Forwarding và sao chép URL có dạng:

https://<ten-ngau-nhien>.ngrok-free.dev

Đây là địa chỉ công khai mà dịch vụ bên ngoài dùng để gọi vào n8n. Giữ cửa sổ này mở; đóng lại là đường hầm ngắt.

Bước 4: Khai báo địa chỉ ngrok cho n8n rồi khởi động lại. n8n không tự biết nó đang nằm sau ngrok, nên node Webhook vẫn hiện URL dạng localhost và các trigger tự đăng ký webhook (Telegram, GitHub…) hay OAuth callback sẽ gửi sai địa chỉ. Tài liệu n8n yêu cầu đặt URL webhook thủ công khi chạy sau proxy (Configure webhook URLs with reverse proxy).

Với n8n chạy bằng Docker, xóa container cũ (dữ liệu nằm trong volume nên không mất) rồi chạy lại với biến mới:

docker stop n8n
docker rm n8n
docker run -d --name n8n --restart unless-stopped -p 5678:5678 \
  -e GENERIC_TIMEZONE="Asia/Ho_Chi_Minh" -e TZ="Asia/Ho_Chi_Minh" \
  -e N8N_WEBHOOK_URL="https://<ten-ngau-nhien>.ngrok-free.dev/" \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n:2.44.6

Giữ đúng volume và các biến -e bạn đã dùng khi cài. N8N_WEBHOOK_URL có từ n8n 2.30.0; bản cũ hơn dùng WEBHOOK_URL (vẫn chạy nhưng bị đánh dấu deprecated từ 2.35.0). Nếu cài bằng npm, đặt biến môi trường trước khi chạy n8n start. Vì dev domain của gói Free cố định, bạn chỉ cần làm bước này một lần.

Thử nghiệm xây dựng workflow n8n lắng nghe webhook qua ngrok

Phần thử nghiệm dưới đây gửi một request POST từ Postman qua ngrok vào node Webhook trên máy, để xác nhận đường hầm hoạt động.

Tạo workflow và lấy URL webhook từ n8n

Mở n8n, tạo workflow mới và thêm node Webhook. Chọn phương thức POST rồi nhấn Listen for test event; n8n chuyển sang trạng thái chờ dữ liệu.

Sau khi đã đặt N8N_WEBHOOK_URL, mục Test URL sẽ có dạng:

https://<ten-ngau-nhien>.ngrok-free.dev/webhook-test/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Ảnh chụp lúc chưa đặt N8N_WEBHOOK_URL nên Test URL vẫn là http://localhost:5678/webhook-test/…. Nếu bạn chưa đặt biến, có thể tự ghép: thay phần http://localhost:5678 bằng địa chỉ ngrok. Cách ghép tay chỉ hợp để thử nhanh một lần; trigger tự đăng ký webhook vẫn cần biến này.

• URL từ ngrok: https://unhectic-unfried-pearly.ngrok-free.dev
• Phần đuôi URL từ n8n (ví dụ): /webhook-test/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• URL thử nghiệm: https://unhectic-unfried-pearly.ngrok-free.dev/webhook-test/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Gửi yêu cầu thử nghiệm với Postman

1. Mở Postman.
2. Tạo request mới, chọn phương thức POST.
3. Dán Test URL ở trên vào thanh địa chỉ.
4. Chuyển sang tab Body, chọn raw và định dạng JSON.
5. Dán đoạn JSON mẫu dưới đây rồi nhấn Send.

{
  "event": "new_user_signup",
  "user_id": "usr_12345",
  "name": "Nguyen Van A",
  "status": "success"
}

Nếu thấy {"message": "Workflow was started"} với mã 200 OK, request đã đi qua ngrok và vào n8n.

Kiểm tra kết quả trong n8n

Quay lại n8n: trạng thái chờ biến mất và node Webhook hiển thị dữ liệu vừa gửi. Dữ liệu JSON nằm trong body, nên ở các node sau bạn đọc bằng {{ $json.body.event }} (Webhook node).

Trong headers có x-forwarded-host là địa chỉ ngrok và x-forwarded-proto: https, cho thấy request đi qua đường hầm. Nhớ nhấn Publish workflow và dùng Production URL khi muốn workflow nhận webhook mà không cần bấm Listen.

Gói Free của ngrok giới hạn những gì?

Gói Free của ngrok đủ cho việc thử webhook n8n, với các giới hạn chính sau (ngrok.com/pricing, 23/10/2026):

Trang cảnh báo chỉ hiện khi mở URL bằng trình duyệt; request từ dịch vụ khác hoặc Postman thường không bị ảnh hưởng. Nếu cần bỏ trang cảnh báo khi tự gọi, thêm header ngrok-skip-browser-warning vào request.

Khi nào không nên dùng ngrok cho n8n?

Không nên dùng ngrok cho n8n chạy thật (production). Máy tính phải bật liên tục, đường hầm ngắt khi đóng cửa sổ hoặc mất mạng, và gói Free có giới hạn request. Khi workflow cần nhận webhook 24/7, hãy đưa n8n lên VPS có tên miền và HTTPS riêng.

Các bước cài n8n bằng Docker Compose trên VPS: hướng dẫn cài đặt n8n trên VPS. Không muốn tự cài, có thể dùng VPS đã cài sẵn n8n.

Kết luận

Với ngrok, n8n trên máy tính nhận được webhook thật để thử và gỡ lỗi workflow. Bốn việc cần nhớ: thêm authtoken, chạy ngrok http 5678, đặt N8N_WEBHOOK_URL bằng dev domain rồi khởi động lại n8n, và giữ cửa sổ ngrok mở trong lúc thử.

Muốn chạy n8n 24/7 mà không tự cài? VPS n8n của Tino cài sẵn n8n trên VPS NVMe đặt tại Việt Nam; bạn vẫn có quyền root để cấu hình. Xem cấu hình và giá trên trang sản phẩm.

Những câu hỏi thường gặp