Webhook sự kiện

Thay vì gọi API liên tục để xem có gì mới, đăng ký webhook để Siêu trợ lý gửi sự kiện tới URL của bạn ngay khi có thay đổi.

Đăng ký

Vào app.sieutroly.ai → Tích hợp → Sự Kiện & Webhook → thêm URL nhận và chọn sự kiện. Nút Kiểm tra cạnh ô URL gửi thử một yêu cầu tới URL. Mỗi đăng ký có một Secret riêng (bấm để hiện) dùng để ký nội dung.

URL phải là địa chỉ công khai (không nhận địa chỉ mạng nội bộ) và không được chuyển hướng.

Sự kiện

Sự kiện	Khi nào
message.incoming	Khách nhắn tới (mọi kênh)
message.sent	Tin đã gửi đi; source = agent (nhân viên) hoặc api (đối tác)
conversation.created	Có hội thoại mới
conversation.status_changed	Hội thoại đổi trạng thái
conversation.assigned	Hội thoại được giao cho nhân viên
customer.created	Có khách hàng mới
customer.updated	Hồ sơ khách thay đổi
customer.labeled	Khách được gắn/bỏ nhãn
order.created	Có đơn mới
order.updated	Đơn thay đổi nội dung
order.status_changed	Đơn đổi trạng thái (có previous_status)
order.paid	Tiền đã về (kèm transaction_id, transferred_amount khi đối soát tự động)
order.deleted	Đơn bị xóa
order.shipping_created	Đã tạo đơn giao hàng cho đơn

Nội dung gửi

POST tới URL của bạn, thân JSON phẳng:

{
  "event": "order.paid",
  "timestamp": "2026-10-10T08:42:11.000Z",
  "workspace_id": "…",
  "order_id": "5f0c…",
  "order_number": "DH20261010-003",
  "payment_code": "SK48213",
  "external_id": "WEB-10025",
  "status": "paid",
  "customer": { "id": "c1…", "name": "Nguyễn An", "phone": "0901234567", "email": "[email protected]" }
}

Header kèm theo:

Header	Giá trị
X-Saleskit-Event	Tên sự kiện
X-Saleskit-Workspace	Id workspace
X-Saleskit-Delivery	Id duy nhất của lần gửi (dùng để bỏ trùng)
X-Saleskit-Timestamp	Thời điểm phát sự kiện
X-Saleskit-Signature	sha256=<HMAC-SHA256 của thân yêu cầu, khóa = khóa bí mật của đăng ký>

Thông tin khách trong sự kiện đơn

Mọi sự kiện order.* có trường customer đầy đủ, là giá trị hiện tại của hồ sơ khách lúc phát sự kiện:

"customer": { "id": "c1…", "name": "Nguyễn An", "phone": "0901234567", "email": "[email protected]", "address": "12 Lê Lợi, Q1", "avatar": null,
  "notes": "khách quen", "gender": "male", "has_purchased": true,
  "labels": [ { "id": "l1…", "name": "VIP", "color": "#f00" } ],
  "custom_fields": [ { "id": "f1…", "name": "Sinh nhật", "type": "text", "value": "01/02" } ],
  "created_at": "2026-10-01T03:00:00Z", "updated_at": "2026-10-10T08:00:00Z" }

Đơn của khách vãng lai (chưa có hồ sơ): { "id": null, "name", "phone", "email" } lấy từ đơn; không có thông tin gì thì null. Các trường customer_name / customer_phone / customer_email là bản chụp lúc tạo đơn, vẫn giữ để tương thích.

Nội dung message.incoming: xem API Hội thoại.

Kiểm tra chữ ký

Tính HMAC-SHA256 trên thân yêu cầu thô (đúng chuỗi byte nhận được, trước khi parse JSON) rồi so với header:

import crypto from 'node:crypto'

function verify(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return header.length === expected.length && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected))
}

Thử lại

Phản hồi không phải 2xx (hoặc quá 10 giây không phản hồi) thì gửi lại: tổng cộng tối đa 3 lần, cách nhau 2 rồi 4 giây. Lịch sử gửi và phản hồi của URL xem ở trang Sự Kiện & Webhook.

Vì có thể nhận một sự kiện hơn một lần, hãy bỏ trùng theo X-Saleskit-Delivery. Đối soát thanh toán thì so khớp nội dung chuyển khoản với payment_code.