Dev local webhook UnifyPort với ngrok

ngrok giải quyết gì

Một lệnh là có URL HTTPS công khai forward mọi request đến một port local. Mọi traffic đi qua được inspector tại http://127.0.0.1:4040 capture — headers, body, thời gian, nút replay đầy đủ. Chính cái inspector này là lý do chúng tôi vẫn dùng ngrok dù đã có nhiều tunnel miễn phí thay thế: nó nén việc lẽ ra phải chạy theo log thành một cái liếc mắt.

Setup 5 phút cho handler UnifyPort

Giả sử handler nghe port 3000:

1. 1. ngrok http 3000 — copy URL https://*.ngrok-free.app nó in ra.
2. 2. Đăng ký URL qua POST /v1/webhook-endpoints — đặt url thành https://<your-tunnel>.ngrok-free.app/events và chọn subscribed_events bạn cần (đang lặp thử có thể dùng ["*"] để nhận hết).
3. 3. Mở http://127.0.0.1:4040 trên trình duyệt. Trigger sự kiện từ phía provider — DM Telegram, tin nhắn WhatsApp — và nhìn nó tới.
4. 4. Dùng nút replay để gửi lại delivery đó cho handler đã cập nhật. Đây là điểm khiến ngrok nhanh hơn nhiều so với việc mỗi lần đổi code lại đi nài provider bắn lại sự kiện.

Xác minh chữ ký ngay tại local

Tunnel ngrok miễn phí kết thúc TLS ở upstream, nên khi handler thấy request thì body đã giải mã — đúng cái UnifyPort đã ký. Nghĩa là verify chữ ký giống y production: tính hex(HMAC-SHA256(secret, timestamp + "." + body)) rồi so với header X-Device-Signature. Nếu muốn xác nhận thủ công trước khi viết code, recipe CyberChef của chúng tôi chạy đúng thuật toán đó trong trình duyệt.

Khi nào ngrok không còn là đáp án tốt nhất

• Môi trường staging hoặc demo. URL miễn phí đổi mỗi khi restart, làm hỏng cấu hình dài hạn. Lên bản trả phí có reserved domain — hoặc chuyển sang Cloudflare Tunnel để có hostname cố định miễn phí.
• Load test cường độ cao. ngrok free throttle khá mạnh. Hoặc upgrade, hoặc chạy handler trên môi trường thật.
• Workflow chỉ có webhook, không có HTTP traffic khác. smee.io nhẹ hơn — không cần binary, chỉ một script client.