Đăng ký webhook
Webhook là kênh để hệ thống Zorio chủ động đẩy sự kiện (cuộc gọi, lead, CDR, ...) sang URL của bạn realtime — thay vì bạn phải poll API liên tục.
Cách đăng ký
Không tự đăng ký qua API
Vì lý do bảo mật + audit (chống abuse token để redirect webhook ra URL ngoài), đăng ký webhook chỉ làm qua giao diện Admin Console, KHÔNG có API CRUD công khai.
Quy trình 5 bước
- Đăng nhập Admin Console với tài khoản admin.
- Vào Cài đặt → Tích hợp → Webhooks (
Admin Console). - Bấm Tạo webhook, điền:
- URL — endpoint HTTPS nhận event (do bạn deploy).
- Events — chọn danh sách event quan tâm (vd
pbx.call.hangup,telesales.lead.updated). - Tên hiển thị — để phân biệt khi có nhiều webhook.
- Hệ thống tự sinh secret (32 ký tự alphanumeric) — copy ngay, không xem lại được.
- Deploy receiver xác minh HMAC (xem Ký HMAC-SHA256) và xử lý event.
Các event hỗ trợ
PBX (xem chi tiết PBX Webhooks)
| Event | Khi nào fire |
|---|---|
pbx.call.ringing | Cuộc gọi vào ext, ext đang đổ chuông |
pbx.call.answered | Ext đã nhấc máy |
pbx.call.hangup | Cuộc gọi kết thúc — realtime từ ESL |
pbx.cdr.created | Pipeline CDR đã insert row đầy đủ + recording_url |
Telesales (xem chi tiết Telesales)
| Event | Khi nào fire |
|---|---|
telesales.lead.created | Lead mới được insert/import |
telesales.lead.updated | Disposition / custom field thay đổi |
telesales.call.disposed | Agent đặt outcome cho cuộc gọi |
telesales.campaign.completed | Toàn bộ lead trong campaign đã được dial |
AutoCall (xem chi tiết AutoCall Webhooks)
| Event | Khi nào fire |
|---|---|
autocall.campaign.started / paused / resumed / finished | Lifecycle campaign |
autocall.lead.dialed / answered / dtmf_pressed / transferred | Lifecycle 1 cuộc gọi |
URL receiver phải đáp ứng
- HTTPS bắt buộc (không nhận HTTP plain).
- Trả về HTTP 2xx trong vòng 5 giây — quá thời gian Zorio coi như fail và retry.
- Idempotent theo header
X-Zorio-Delivery(UUID) — Zorio có thể retry cùng 1 event nếu lần trước fail. - Verify HMAC trước khi xử lý — xem Ký HMAC-SHA256.
Test webhook
Trong Admin Console có nút Send test event — gửi payload mẫu để bạn debug receiver mà không cần chờ event thật.
Xoay secret
Nếu nghi ngờ secret bị lộ:
- Vào Admin Console → mục webhook → Xoay secret.
- Hệ thống sinh secret mới — copy + update vào receiver.
- Secret cũ disable ngay lập tức — event tiếp theo sẽ ký bằng secret mới.
Tạm dừng / Xoá webhook
- Tạm dừng: webhook giữ cấu hình, không gửi event. Phù hợp khi receiver đang bảo trì.
- Xoá: vĩnh viễn, history giữ trong audit log nhưng không thể restore.
Xem nhật ký delivery
Mỗi event gửi đi có delivery record lưu trong 30 ngày:
- Endpoint, event, timestamp, status code receiver trả về.
- Payload đầy đủ + response body.
- Số lần retry.
Truy cập tại Admin Console → Webhook deliveries.