Đă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 (ngăn chặn việc lạm dụng 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

1. Đăng nhập Admin Console với tài khoản admin.
2. Vào Cài đặt → Tích hợp → Webhooks (Admin Console).
3. Bấm Tạo webhook, điền: URL — địa chỉ HTTPS nhận webhook
   • 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.
4. Hệ thống tự sinh secret (32 ký tự alphanumeric) — copy ngay, không xem lại được.
5. Triển khai 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 — theo thời gian thực 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 kiểm thử receiver mà không cần chờ event thật.

Xoay secret

Nếu nghi ngờ secret bị lộ:

1. Vào Admin Console → mục webhook → Xoay secret.
2. Hệ thống sinh secret mới — copy + update vào receiver.
3. 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, lịch sử vẫn được lưu trong nhật ký kiểm toán nhưng không thể khôi phục.

Xem nhật ký delivery

Mỗi event gửi đi có delivery record lưu trong 30 ngày:

• Địa chỉ nhận, sự kiện, thời điểm gửi, mã trạng thái HTTP do receiver trả về.
• Payload đầy đủ + response body.
• Số lần retry.

Truy cập tại Admin Console → Webhook deliveries.