Webhook cho Zapier, Make và n8n

Webhook báo cho một công cụ khác biết có chuyện vừa xảy ra trong Hạ Tầng, chỉ sau vài giây. Mỗi khi một sự kiện bạn đăng ký diễn ra (một đơn được thanh toán, khách mở cuộc hội thoại, tiền chuyển khoản về), Hạ Tầng gửi thông tin chi tiết tới một địa chỉ do bạn chọn.

Với công cụ no-code như Zapier, Make hay n8n, chừng đó đủ để dựng các quy trình tự động hữu ích mà không cần lập trình viên:

• Thêm mỗi đơn đã thanh toán thành một dòng trong Google Sheets.
• Báo vào nhóm chat của đội khi khách đánh giá 1 sao.
• Tạo liên hệ trong CRM bán hàng khi có hội thoại mới.
• Báo cho phần mềm kế toán mỗi khoản chuyển khoản nhận được.

Bạn cần quyền Developer (API key, webhook), chủ sở hữu và quản trị viên luôn có quyền này.

Thêm webhook

1. Trong công cụ no-code, tạo một bước kích hoạt nhận webhook và chép URL của nó:
   • Zapier: Webhooks by Zapier → Catch Hook.
   • Make: Webhooks → Custom webhook.
   • n8n: node Webhook với phương thức POST (dùng production URL khi workflow đã bật).
2. Trong Hạ Tầng, mở Cài đặt → Webhooks.
3. Dán URL vào ô trên cùng.
4. Đánh dấu các sự kiện bạn cần và bỏ các sự kiện khác. Vài sự kiện hay dùng đã được chọn sẵn.
5. Bấm Thêm endpoint.

Trang của endpoint mở ra và hiện Secret ký (chỉ hiển thị một lần):. Hãy chép lại nếu lập trình viên sẽ kiểm tra chữ ký; secret không hiện lại nữa.

Để thử, cho sự kiện xảy ra một lần (ví dụ tạo một đơn thử trong hội thoại), rồi xem mục Lượt gửi trên trang endpoint và dữ liệu nhận được trong công cụ của bạn.

Chọn sự kiện nào

Chỉ đăng ký những gì quy trình cần: mỗi sự kiện là một lần gửi, và nhiều công cụ tính số lần gửi vào gói cước của bạn.

Danh sách đầy đủ, cùng nội dung của từng sự kiện, nằm trong tài liệu sự kiện webhook.

Hạ Tầng gửi gì

Mỗi sự kiện là một yêu cầu HTTP POST với nội dung JSON:

{
  "type": "chat.order.paid",
  "created_at": "2026-10-24T08:15:00.000Z",
  "data": { "code": "DH000014", "total": 2530000, "payment_status": "paid", "...": "..." }
}

Trong Zapier, Make hay n8n, phần data hiện thành các trường để bạn đưa vào bước tiếp theo: mã đơn, tổng tiền, tên và số điện thoại người nhận, v.v.

Mỗi yêu cầu còn kèm các header chữ ký (webhook-id, webhook-timestamp, webhook-signature, và cùng giá trị đó dưới tên svix-*). Lập trình viên dùng chúng cùng secret ký để chứng minh yêu cầu thật sự đến từ Hạ Tầng. Công cụ no-code thường bỏ qua bước này, nên hãy giữ kín URL webhook: ai có URL đều gửi được dữ liệu giả vào đó. Cách kiểm tra chữ ký có trong hướng dẫn webhook dành cho lập trình viên.

Lượt gửi, gửi lại tự động và gửi lại bằng tay

Trang endpoint liệt kê mọi Lượt gửi: sự kiện, Trạng thái, số Lần thử, Phản hồi công cụ của bạn trả về và thời gian phản hồi, cùng Thử lại lúc. Bấm vào tên sự kiện để xem dữ liệu đã gửi và câu trả lời nhận được.

• Công cụ của bạn phải trả lời mã 2xx trong vòng 15 giây.
• Nếu không, Hạ Tầng thử lại sau 5 giây, 5 phút, 30 phút, 2 giờ, 5 giờ, 10 giờ và 10 giờ. Sau đó lượt gửi chuyển sang Hết lượt thử.
• Gửi lại gửi lại một lượt với cùng webhook-id, để công cụ của bạn nhận ra đó là bản lặp.

Quản lý endpoint

Trên trang endpoint:

• Tắt dừng endpoint: không gửi gì nữa, các lượt đang chờ thử lại bị bỏ. Bật cho endpoint nhận lại sự kiện mới.
• Đổi secret tạo secret ký mới, chỉ hiện một lần. Trong 24 giờ sau đó, yêu cầu được ký bằng cả secret cũ và mới, để lập trình viên có thời gian chuyển.
• Xoá xoá endpoint và dừng mọi lượt gửi của nó.

Muốn đổi sự kiện, hãy thêm endpoint mới với đúng sự kiện rồi xoá endpoint cũ.

Xử lý sự cố