Webhook events PBX

Đăng ký webhook

Webhook là cấu hình của khách hàng — đăng ký / xoá / xoay secret qua giao diện Admin (Admin Console). API công khai không hỗ trợ CRUD cho Webhook Subscription.

Tài liệu này document payload schema + HMAC verify để CRM khách hàng tự xử lý event nhận về.

Envelope chung

Mọi event đều có cấu trúc envelope:

Field	Type	Mô tả
event	string	Tên event (xem chi tiết bên dưới)
timestamp	datetime	Lúc Zorio publish event (ISO 8601 UTC)
data	object	Payload tương ứng với từng Event.

pbx.call.ringing

Cuộc gọi tới ext, ext đang đổ chuông chưa nhấc.

data fields

Field	Type	Mô tả	Giá trị
call_uuid	string	UUID cuộc gọi
extension	string	Số máy nhánh đang đổ chuông
direction	string	Hướng cuộc gọi	inbound / outbound / internal
caller_number	string	Số gọi đi (caller ID)
destination_number	string	Số đích (thường = extension)
timestamp	datetime	Lúc bắt đầu đổ chuông	ISO 8601

Sample payload

{
  "event": "pbx.call.ringing",
  "timestamp": "2026-06-29T03:30:00Z",
  "data": {
    "call_uuid": "...",
    "extension": "1001",
    "direction": "inbound",
    "caller_number": "0987654321",
    "destination_number": "0900000020",
    "timestamp": "2026-06-29T03:30:00Z"
  }
}

pbx.call.answered

Máy nhánh đã nhấc máy.

data fields = giống pbx.call.ringing + thêm:

Field	Type	Mô tả
answered_at	datetime	Lúc nhấc máy (ISO 8601)

pbx.call.hangup

Cuộc gọi kết thúc — được gửi ngay khi cuộc gọi kết thúc kết thúc cuộc gọi từ Zorio PBX.

data fields

Field	Type	Mô tả	Giá trị hợp lệ
call_uuid	string	UUID cuộc gọi
extension	string	Máy nhánh liên quan
direction	string	Hướng cuộc gọi	inbound / outbound / internal
caller_number	string	Caller ID
destination_number	string	Số đích
started_at	datetime|null	Lúc cuộc gọi bắt đầu (thời điểm bắt đầu cuộc gọi)	ISO 8601
answered_at	datetime|null	Lúc nhấc máy (null nếu không nhấc)	ISO 8601
ended_at	datetime	Lúc cúp máy	ISO 8601
duration_sec	integer	Tổng thời lượng (giây)	≥ 0
billsec	integer	Thời gian tính tiền (giây)	≥ 0
hangup_cause	string	Mã hangup chuẩn Q.850 từ Zorio PBX	NORMAL_CLEARING / NO_ANSWER / USER_BUSY / CALL_REJECTED / ORIGINATOR_CANCEL / ...
call_result	string	Kết quả phân loại nhanh	answered (billsec > 0) / no_answer (billsec = 0)
recording_url	string|null	URL tải ghi âm — null ở Webhook thời gian thực (gửi ngay khi cúp), URL có giá trị ở pbx.cdr.created (sau khi pipeline ghi âm xong)

Sample payload

{
  "event": "pbx.call.hangup",
  "timestamp": "2026-06-29T03:30:45Z",
  "data": {
    "call_uuid": "...",
    "extension": "1001",
    "direction": "inbound",
    "caller_number": "0987654321",
    "destination_number": "0900000020",
    "started_at": "2026-06-29T03:30:00Z",
    "answered_at": "2026-06-29T03:30:03Z",
    "ended_at": "2026-06-29T03:30:45Z",
    "duration_sec": 45,
    "billsec": 42,
    "hangup_cause": "NORMAL_CLEARING",
    "call_result": "answered",
    "recording_url": null
  }
}

pbx.cdr.created

Được gửi sau khi CDR được ghi vào cơ sở dữ liệu. — có đầy đủ field từ sau khi xử lý hoàn tất A-leg và B-leg + recording_url.

data fields

Field	Type	Mô tả	Giá trị hợp lệ
call_uuid	string	UUID cuộc gọi (= UUID cuộc gọi)
extension	string|null	Máy nhánh (ưu tiên extension_number, fallback agent_extension)
direction	string	Hướng	inbound / outbound / internal / local
caller_number	string	Caller ID
destination_number	string	Số đích
started_at	datetime|null	Lúc bắt đầu	ISO 8601
answered_at	datetime|null	Lúc nhấc	ISO 8601
ended_at	datetime|null	Lúc cúp	ISO 8601
duration_sec	integer	Tổng thời lượng	≥ 0
billsec	integer	Thời gian tính tiền	≥ 0
hangup_cause	string	Mã hangup	(như pbx.call.hangup)
result	string	Kết quả phân loại đầy đủ	answered / busy / no_answer / failed / cancelled / rejected / voicemail
recording_url	string|null	URL nội bộ trỏ tới endpoint download (yêu cầu Bearer Token)	https://app.zorio.vn/api/pbx/cdr/{uuid}/recording hoặc null

Khác biệt với pbx.call.hangup

• pbx.call.hangup fire ngay từ sự kiện thời gian thực — result chỉ ở mức coarse (answered / no_answer).
• pbx.cdr.created fire sau khi hệ thống xử lý CDR hoàn tất → result phân loại chi tiết hơn + có recording_url.

Headers POST từ Zorio tới URL khách

Header	Ý nghĩa
X-Zorio-Event	pbx.call.hangup
X-Zorio-Timestamp	epoch giây (UTC). Client nên từ chối nếu lệch quá 300 giây.
X-Zorio-Delivery	UUID của từng lần gửi, dùng để loại bỏ bản ghi trùng khi Retry.
X-Zorio-Signature	sha256=<hex> HMAC-SHA256(secret, raw_body)
Content-Type	application/json; charset=utf-8

Xác thực HMAC phía Client (mẫu Node.js)

const crypto = require('crypto');

function verify(req, secret) {
  const ts = parseInt(req.headers['x-zorio-timestamp'], 10);
  if (Math.abs(Date.now() / 1000 - ts) > 300) return false;
  const sig = req.headers['x-zorio-signature'];
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(req.rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Retry policy

Zorio kỳ vọng client trả 2xx trong 5 giây. Nếu không:

• Lần 2: sau 30 giây
• Lần 3: sau 5 phút
• Lần 4: sau 30 phút
• Max 4 lần → đánh dấu deadletter trong bảng nhật ký phân phối webhook

Client nên trả 200 ngay khi nhận event, xử lý bất đồng bộ (asynchronous) — tránh bị Retry lặp lại nhiều lần.