Sự kiện webhook

Hạ Tầng gửi một POST cho mỗi sự kiện tới từng webhook đã đăng ký sự kiện đó. Body luôn cùng một khung; data tuỳ theo sự kiện. Mỗi sự kiện dưới đây dẫn tới schema đầy đủ của payload và ví dụ.

Khung dữ liệu

{
  "type": "email.delivered",
  "created_at": "2026-10-23T08:15:00.000Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Shop <[email protected]>",
    "to": [
      "[email protected]"
    ],
    "subject": "Your order",
    "created_at": "2026-10-23T08:14:58.000Z"
  }
}

Header

Header	Ý nghĩa
svix-id / webhook-id	Id duy nhất của lần gửi. Gửi lại và phát lại dùng cùng id: hãy chống trùng theo id này.
svix-timestamp / webhook-timestamp	Thời điểm ký (giây Unix). Từ chối nếu lệch quá 5 phút.
svix-signature / webhook-signature	Chữ ký dạng v1,<base64>, cách nhau bằng dấu cách (có hai chữ ký trong lúc đổi secret).

Trả về bất kỳ mã 2xx nào trong 15 giây. Mã khác hoặc quá thời gian sẽ được gửi lại sau 5 giây, 5 phút, 30 phút, 2 giờ, 5 giờ, 10 giờ và 10 giờ. Bạn có thể phát lại bất kỳ lần gửi nào trong dashboard hoặc bằng POST /webhooks/deliveries/{id}/replay.

Cách tạo webhook, mã xác minh chữ ký và cách kiểm thử có trong hướng dẫn Webhook.

Sự kiện Email

Sự kiện	Khi nào được gửi
email.sent	Email đã được hạ tầng gửi chấp nhận.
email.delivered	Máy chủ thư của người nhận đã nhận email.
email.delivery_delayed	Đang thử gửi lại (ví dụ máy chủ người nhận tạm từ chối).
email.bounced	Email bị trả về. data.bounce.type là Permanent (địa chỉ bị chặn) hoặc Transient.
email.complained	Người nhận đánh dấu spam. Địa chỉ bị chặn.
email.opened	Người nhận mở email (khi bật theo dõi mở). Mỗi lần mở một sự kiện.
email.clicked	Người nhận bấm một liên kết được theo dõi. data.click.link là URL gốc.
email.failed	Không gửi được email. data.failed.reason cho biết lý do.
email.received	Có email tới một tên miền nhận thư của bạn. Lấy nội dung và tệp đính kèm bằng API Receiving.
contact.created	Có liên hệ mới (API, dashboard, nhập file hoặc đồng bộ CRM).
contact.updated	Tên, thuộc tính hoặc trạng thái đăng ký của liên hệ thay đổi.
contact.deleted	Liên hệ bị xoá.
domain.created	Đã thêm tên miền gửi.
domain.updated	Tên miền thay đổi, kể cả trạng thái xác minh.
domain.deleted	Tên miền bị xoá.

Sự kiện Hỗ trợ

Sự kiện	Khi nào được gửi
chat.conversation.created	Có hội thoại mới trên bất kỳ kênh nào.
chat.conversation.assigned	Hội thoại được giao (hoặc bỏ giao).
chat.conversation.resolved	Hội thoại được đánh dấu đã xử lý.
chat.conversation.closed	Hội thoại bị đóng.
chat.conversation.reopened	Hội thoại đã xử lý hoặc đã đóng được mở lại.
chat.conversation.handoff	Trợ lý AI chuyển hội thoại cho nhân viên.
chat.conversation.tagged	Hội thoại được gắn thêm tag; mỗi tag một sự kiện.
chat.message.created	Có tin nhắn công khai từ khách, nhân viên, trợ lý AI hoặc kịch bản. Ghi chú nội bộ không gửi sự kiện này.
chat.visitor.identified	Khách được nhận diện (identify từ widget hoặc SDK).
chat.order.created	Đơn hàng được tạo từ hộp thư hoặc API.
chat.order.updated	Đơn hàng thay đổi (trạng thái, sản phẩm, vận chuyển).
chat.order.paid	Đơn hàng đã được thanh toán.
chat.flow.webhook	Kịch bản hoặc quy trình chạy tới bước Webhook.
chat.campaign.lead	Khách gửi form thu thập thông tin.
chat.ticket.created	Phiếu hỗ trợ được tạo.
chat.ticket.updated	Phiếu hỗ trợ thay đổi.
chat.ticket.resolved	Phiếu hỗ trợ được xử lý xong.
chat.ticket.breached	Phiếu trễ một mốc SLA. clock cho biết mốc nào.
chat.rating.created	Khách đánh giá hội thoại (CSAT).
chat.zns.sent	Tin Zalo ZNS đã gửi tới Zalo.
chat.zns.failed	Tin Zalo ZNS gửi lỗi. error có lý do.

Sự kiện Thanh toán

Sự kiện	Khi nào được gửi
payment.created	Yêu cầu thanh toán được tạo.
payment.succeeded	Đã nhận đủ tiền.
payment.partially_paid	Nhận được ít hơn số tiền yêu cầu.
payment.overpaid	Nhận được nhiều hơn số tiền yêu cầu.
payment.expired	Thanh toán hết hạn trước khi được trả.
payment.canceled	Thanh toán bị huỷ.
transaction.received	Có tiền vào một tài khoản ngân hàng đã liên kết (khớp hoặc chưa khớp).
bank_connection.activated	Tài khoản ngân hàng đã liên kết và xác nhận.
bank_connection.revoked	Liên kết ngân hàng bị gỡ.
bank_connection.needs_reauth	Ngân hàng cần chủ tài khoản xác nhận lại liên kết.
invoice.draft_created	Hoá đơn nháp được tạo.
invoice.draft_updated	Hoá đơn nháp thay đổi.
invoice.draft_deleted	Hoá đơn nháp bị xoá.
invoice.issued	Nhà cung cấp đã phát hành hoá đơn điện tử.
invoice.tax_accepted	Cơ quan thuế chấp nhận hoá đơn.
invoice.tax_rejected	Cơ quan thuế từ chối hoá đơn.
invoice.canceled	Hoá đơn bị huỷ.
invoice.replaced	Hoá đơn được thay thế bằng hoá đơn mới.
invoice.adjusted	Đã phát hành hoá đơn điều chỉnh.
invoice.failed	Phát hành hoá đơn điện tử thất bại.
invoice.conflict	Hoá đơn bị sửa phía nhà cung cấp và xung đột với bản trên Hạ Tầng.