D2 · Developer flow — Webhooks

🛠 Dành cho IT / Lập trình viên

Trang flow này dành cho bộ phận IT trong doanh nghiệp. Người dùng cuối có thể bỏ qua.

CNV Work cho phép subscribe sự kiện realtime (lead created, deal won, message received…). Khi event xảy ra trong workspace, hệ thống POST payload JSON đến URL bạn đăng ký, có signature HMAC-SHA256 để xác minh nguồn gốc.

D2.1 · Đăng ký webhook endpoint

🟠 Quy tắc nghiệp vụ. URL phải là HTTPS (TLS 1.2+). Signing secret chỉ hiện 1 lần — copy ngay. Endpoint không reachable lúc đăng ký vẫn lưu (warn) — có thể test thủ công sau khi sửa.

D2.2 · Event firing & POST tới endpoint

🟠 Quy tắc nghiệp vụ. Worker timeout request 30 giây. Idempotency: mỗi delivery có X-CNV-Delivery-Id duy nhất — bạn nên dedupe phía mình (cache delivery_id 24h) để tránh process trùng khi retry.

D2.3 · Retry policy

🟠 Quy tắc nghiệp vụ. Tổng 5 lần retry trong ~15 giờ. Sau retry cuối: log dead + notify Admin qua email. Webhook tự auto-disable nếu >50% delivery fail trong 24h gần nhất (chống endpoint chết kéo dài làm chậm bus). Admin re-enable thủ công sau khi fix.

D2.4 · Verify signature HMAC-SHA256

🟠 Quy tắc nghiệp vụ. Phải so sánh constant-time (crypto.timingSafeEqual Node, hmac.compare_digest Python) — không dùng === thường, dễ bị timing attack. Phải verify trên raw body bytes trước khi parse JSON, vì parser có thể normalize space/order, làm hash khác.

D2.5 · Catalog event hỗ trợ

Module	Events
CRM	lead.created, lead.updated, lead.converted, contact.*, company.*, deal.created, deal.stage_changed, deal.won, deal.lost, quotation.*, invoice.*, payment.received
Inbox	message.received, message.sent, conversation.assigned, conversation.closed, agent.handoff_requested
HR	employee.created, employee.terminated, attendance.checked_in, attendance.late, leave.requested, leave.approved
Tasks	task.created, task.assigned, task.completed, task.overdue
Approvals	approval.requested, approval.approved, approval.rejected, approval.cancelled
Tickets	ticket.created, ticket.assigned, ticket.replied, ticket.resolved, ticket.sla_breached

🟠 Quy tắc nghiệp vụ. Mỗi event có schema cố định, version qua X-CNV-Event-Version: v1. Khi schema thay đổi (vd: thêm field), CNV bump version + giữ song song 6 tháng + email warn deprecated.

D2.6 · Test webhook + log review

🟠 Quy tắc nghiệp vụ. Replay không bypass retry counter — nó là delivery mới với delivery_id mới. Logs retention 30 ngày (Free), 90 ngày (Pro), 1 năm (Business).