Webhooks

Webhook gửi sự kiện tới endpoint HTTPS của tổ chức bạn, ký HMAC để bạn xác minh nguồn. Sự kiện hiện có:

Sự kiện	Khi nào
session.ended	Một phiên hội thoại kết thúc
lead.created	Agent thu được lead từ người dùng
handoff.requested	Người dùng hoặc agent yêu cầu gặp nhân viên

Cấu hình

Trong Studio, mở mục Webhooks và thêm endpoint (bắt buộc https, không trỏ vào địa chỉ nội bộ — server không theo redirect 3xx khi giao). Secret whsec_… hiển thị một lần khi tạo — lưu ngay.

Xác minh chữ ký

Mỗi lần giao kèm header Avatin-Signature:

Avatin-Signature: t=<unix giây>,v1=<HMAC-SHA256(secret, "<t>.<thân thô>")>

Ví dụ kiểm chứng (Node):

const sig = req.headers["avatin-signature"] ?? "";
const [, tPart, v1Part] = sig.match(/^t=(\d+),v1=([a-f0-9]+)$/) ?? [];
const fresh = tPart && Math.abs(Date.now() / 1000 - Number(tPart)) <= 300; // dung sai 300 s
const expected = crypto
  .createHmac("sha256", WHSEC)
  .update(`${tPart}.${rawBody}`) // thân THÔ, chưa parse
  .digest("hex");
const ok = fresh && crypto.timingSafeEqual(Buffer.from(v1Part, "hex"), Buffer.from(expected, "hex"));

Dung sai 300 giây chống phát lại: gói có t cũ hơn 5 phút bị coi là hết hạn.

Giao “ít nhất một lần”

• Retry theo backoff; bên nhận phải khử trùng lặp bằng mã sự kiện trong payload.
• Endpoint thất bại liên tiếp 10 lần sẽ tự tắt — mở lại trong Studio.
• Endpoint nhận được nên trả 2xx sớm và xử lý bất đồng bộ; xử lý chậm gây timeout được tính là thất bại.

Payload mẫu session.ended

{
  "type": "session.ended",
  "orgId": "…",
  "data": {
    "sessionId": "…",
    "agentId": "…",
    "endReason": "ended",
    "durationSeconds": 214
  }
}

Khuyến nghị triển khai

• Lưu raw body rồi xác minh chữ ký trước khi parse JSON.
• Ghi log Avatin-Delivery (mã giao mỗi lần) khi liên hệ hỗ trợ về vấn đề giao nhận.
• Dùng lead.created để đẩy lead vào CRM ngay — không đợi người dùng mở trang hội thoại.