Hướng dẫn webhook cho Zapier và Make

1. Bạn cần gì

Một tài khoản QR Wait mà bạn là chủ sở hữu (quản lý và nhân viên không thấy phần tích hợp), một tài khoản Zapier hoặc Make, và màn hình Tích hợp của trang quản trị mở ở một tab khác.

2. Zapier

1. Trong Zapier, tạo một Zap với Webhooks by Zapier làm trigger và Catch Hook làm sự kiện. Sao chép URL webhook mà Zapier hiển thị.
2. Trong QR Wait, tại Tích hợp, dán URL vào Địa chỉ nhận (https), đánh dấu các sự kiện bạn muốn và nhấn Thêm webhook. Hãy giữ lại khóa bí mật để ký chỉ hiện một lần.
3. Lấy số vào hàng chờ của bạn một lần từ điện thoại, hoặc thêm một người trên bảng điều khiển nhân viên, để một sự kiện ticket.joined thật được gửi đến. Gửi sự kiện thử chỉ gửi một ping không có các trường của phiếu: nó cho thấy địa chỉ có phản hồi.
4. Quay lại Zapier, kiểm tra trigger và chọn sự kiện đó. Thêm một action, ví dụ Google Sheets › Create Spreadsheet Row, và ánh xạ các trường: type, queue.name, ticket.no, ticket.size, ticket.joined_at.
5. Xuất bản Zap. Từ giờ, mỗi sự kiện sẽ thêm một hàng.

3. Make

1. Trong Make, tạo một scenario có module đầu tiên là Webhooks › Custom webhook. Thêm một webhook và sao chép địa chỉ của nó.
2. Dán địa chỉ vào Tích hợp của QR Wait như trên và nhấn Thêm webhook.
3. Make chờ để nhận biết cấu trúc dữ liệu: hãy lấy số vào hàng chờ của bạn một lần hoặc thêm một người trên bảng điều khiển nhân viên.
4. Thêm module tiếp theo, ví dụ Google Sheets › Add a Row hoặc một tin nhắn đến kênh chat của bạn, ánh xạ các trường và bật scenario.

4. Dữ liệu nhận được

Mỗi sự kiện là một body JSON như ví dụ này. Chỉ đánh dấu các sự kiện bạn cần trong QR Wait, hoặc lọc theo type trong Zapier hoặc Make.

{
  "id": "d_3f9a1c0b7e2d4a61",
  "type": "ticket.joined",
  "created": "2026-10-10T09:12:30.010Z",
  "account": "antalyabb",
  "queue": { "id": "a1b2c3d4e5", "name": "Konyaaltı Beach", "slug": "konyaalti" },
  "ticket": { "no": 42, "size": 2, "source": "qr", "joined_at": "2026-10-10T09:12:30.004Z" }
}

Tên, câu trả lời trong biểu mẫu lấy số và mã đặt lịch chỉ được gửi nếu bạn đánh dấu Gửi kèm tên, câu trả lời trong biểu mẫu lấy số và mã đặt lịch cho địa chỉ đó. Nếu không, sự kiện chỉ chứa số thứ tự và thời gian.

Lần gửi thất bại sẽ được thử lại trong khoảng 9 giờ với cùng id. Hãy kiểm tra giá trị này trước khi thêm hàng (một bước tra cứu) nếu việc trùng lặp gây ảnh hưởng.

5. Chiều ngược lại: thêm người từ Zapier hoặc Make

Để một công cụ khác đưa người vào hàng chờ (biểu mẫu trên trang web, công cụ đặt lịch), hãy tạo một khóa tại Khóa API với quyền Đọc và ghi và gửi yêu cầu từ Webhooks by Zapier › POST hoặc HTTP › Make a request của Make:

POST https://qrwait.app/api/v1/queues/<queue id>/tickets
Authorization: Bearer qrw_…
Content-Type: application/json

{ "size": 2, "note": "Website" }

Phản hồi là số thứ tự mới, chẳng hạn { "no": 43 }. Mã hàng chờ lấy từ GET /api/v1/queues. Cách gọi nhóm tiếp theo, đánh dấu đã phục vụ và mọi trường đều có trong tài liệu tham khảo API (bằng tiếng Anh).

6. Giữ an toàn

• Địa chỉ mà Zapier hoặc Make cung cấp đủ để gửi dữ liệu vào Zap hoặc scenario của bạn: đừng chia sẻ địa chỉ đó.
• Zapier và Make không tự kiểm tra chữ ký của QR Wait. Nếu bên nhận cần chắc chắn một sự kiện đến từ QR Wait, hãy xác minh header X-QRWait-Signature như tài liệu tham khảo API hướng dẫn, ví dụ trong một bước code.
• Chỉ cấp cho khóa quyền truy cập cần thiết, và thu hồi khóa trên màn hình Tích hợp khi không còn dùng; màn hình này hiển thị lần cuối mỗi khóa được sử dụng.