# 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

```json
{
  "type": "email.delivered",
  "created_at": "2026-10-23T08:15:00.000Z",
  "data": {
    "email_id": "4ef9a417-02e9-4d39-ad75-9611e0fcc33c",
    "from": "Shop <hello@shop.vn>",
    "to": [
      "an@example.com"
    ],
    "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](https://hatang.dev/vi/docs/guides/getting-started/webhooks.md).

## Sự kiện Email

| Sự kiện | Khi nào được gửi |
|---|---|
| [`email.sent`](https://hatang.dev/vi/docs/reference/api/webhook-email-sent) | Email đã được hạ tầng gửi chấp nhận. |
| [`email.delivered`](https://hatang.dev/vi/docs/reference/api/webhook-email-delivered) | Máy chủ thư của người nhận đã nhận email. |
| [`email.delivery_delayed`](https://hatang.dev/vi/docs/reference/api/webhook-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`](https://hatang.dev/vi/docs/reference/api/webhook-email-bounced) | Email bị trả về. `data.bounce.type` là `Permanent` (địa chỉ bị chặn) hoặc `Transient`. |
| [`email.complained`](https://hatang.dev/vi/docs/reference/api/webhook-email-complained) | Người nhận đánh dấu spam. Địa chỉ bị chặn. |
| [`email.opened`](https://hatang.dev/vi/docs/reference/api/webhook-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`](https://hatang.dev/vi/docs/reference/api/webhook-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`](https://hatang.dev/vi/docs/reference/api/webhook-email-failed) | Không gửi được email. `data.failed.reason` cho biết lý do. |
| [`email.received`](https://hatang.dev/vi/docs/reference/api/webhook-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`](https://hatang.dev/vi/docs/reference/api/webhook-contact-created) | Có liên hệ mới (API, dashboard, nhập file hoặc đồng bộ CRM). |
| [`contact.updated`](https://hatang.dev/vi/docs/reference/api/webhook-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`](https://hatang.dev/vi/docs/reference/api/webhook-contact-deleted) | Liên hệ bị xoá. |
| [`domain.created`](https://hatang.dev/vi/docs/reference/api/webhook-domain-created) | Đã thêm tên miền gửi. |
| [`domain.updated`](https://hatang.dev/vi/docs/reference/api/webhook-domain-updated) | Tên miền thay đổi, kể cả trạng thái xác minh. |
| [`domain.deleted`](https://hatang.dev/vi/docs/reference/api/webhook-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`](https://hatang.dev/vi/docs/reference/api/webhook-chat-conversation-created) | Có hội thoại mới trên bất kỳ kênh nào. |
| [`chat.conversation.assigned`](https://hatang.dev/vi/docs/reference/api/webhook-chat-conversation-assigned) | Hội thoại được giao (hoặc bỏ giao). |
| [`chat.conversation.resolved`](https://hatang.dev/vi/docs/reference/api/webhook-chat-conversation-resolved) | Hội thoại được đánh dấu đã xử lý. |
| [`chat.conversation.closed`](https://hatang.dev/vi/docs/reference/api/webhook-chat-conversation-closed) | Hội thoại bị đóng. |
| [`chat.conversation.reopened`](https://hatang.dev/vi/docs/reference/api/webhook-chat-conversation-reopened) | Hội thoại đã xử lý hoặc đã đóng được mở lại. |
| [`chat.conversation.handoff`](https://hatang.dev/vi/docs/reference/api/webhook-chat-conversation-handoff) | Trợ lý AI chuyển hội thoại cho nhân viên. |
| [`chat.conversation.tagged`](https://hatang.dev/vi/docs/reference/api/webhook-chat-conversation-tagged) | Hội thoại được gắn thêm tag; mỗi tag một sự kiện. |
| [`chat.message.created`](https://hatang.dev/vi/docs/reference/api/webhook-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`](https://hatang.dev/vi/docs/reference/api/webhook-chat-visitor-identified) | Khách được nhận diện (`identify` từ widget hoặc SDK). |
| [`chat.order.created`](https://hatang.dev/vi/docs/reference/api/webhook-chat-order-created) | Đơn hàng được tạo từ hộp thư hoặc API. |
| [`chat.order.updated`](https://hatang.dev/vi/docs/reference/api/webhook-chat-order-updated) | Đơn hàng thay đổi (trạng thái, sản phẩm, vận chuyển). |
| [`chat.order.paid`](https://hatang.dev/vi/docs/reference/api/webhook-chat-order-paid) | Đơn hàng đã được thanh toán. |
| [`chat.flow.webhook`](https://hatang.dev/vi/docs/reference/api/webhook-chat-flow-webhook) | Kịch bản hoặc quy trình chạy tới bước Webhook. |
| [`chat.campaign.lead`](https://hatang.dev/vi/docs/reference/api/webhook-chat-campaign-lead) | Khách gửi form thu thập thông tin. |
| [`chat.ticket.created`](https://hatang.dev/vi/docs/reference/api/webhook-chat-ticket-created) | Phiếu hỗ trợ được tạo. |
| [`chat.ticket.updated`](https://hatang.dev/vi/docs/reference/api/webhook-chat-ticket-updated) | Phiếu hỗ trợ thay đổi. |
| [`chat.ticket.resolved`](https://hatang.dev/vi/docs/reference/api/webhook-chat-ticket-resolved) | Phiếu hỗ trợ được xử lý xong. |
| [`chat.ticket.breached`](https://hatang.dev/vi/docs/reference/api/webhook-chat-ticket-breached) | Phiếu trễ một mốc SLA. `clock` cho biết mốc nào. |
| [`chat.rating.created`](https://hatang.dev/vi/docs/reference/api/webhook-chat-rating-created) | Khách đánh giá hội thoại (CSAT). |
| [`chat.zns.sent`](https://hatang.dev/vi/docs/reference/api/webhook-chat-zns-sent) | Tin Zalo ZNS đã gửi tới Zalo. |
| [`chat.zns.failed`](https://hatang.dev/vi/docs/reference/api/webhook-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`](https://hatang.dev/vi/docs/reference/api/webhook-payment-created) | Yêu cầu thanh toán được tạo. |
| [`payment.succeeded`](https://hatang.dev/vi/docs/reference/api/webhook-payment-succeeded) | Đã nhận đủ tiền. |
| [`payment.partially_paid`](https://hatang.dev/vi/docs/reference/api/webhook-payment-partially-paid) | Nhận được ít hơn số tiền yêu cầu. |
| [`payment.overpaid`](https://hatang.dev/vi/docs/reference/api/webhook-payment-overpaid) | Nhận được nhiều hơn số tiền yêu cầu. |
| [`payment.expired`](https://hatang.dev/vi/docs/reference/api/webhook-payment-expired) | Thanh toán hết hạn trước khi được trả. |
| [`payment.canceled`](https://hatang.dev/vi/docs/reference/api/webhook-payment-canceled) | Thanh toán bị huỷ. |
| [`transaction.received`](https://hatang.dev/vi/docs/reference/api/webhook-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`](https://hatang.dev/vi/docs/reference/api/webhook-bank-connection-activated) | Tài khoản ngân hàng đã liên kết và xác nhận. |
| [`bank_connection.revoked`](https://hatang.dev/vi/docs/reference/api/webhook-bank-connection-revoked) | Liên kết ngân hàng bị gỡ. |
| [`bank_connection.needs_reauth`](https://hatang.dev/vi/docs/reference/api/webhook-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`](https://hatang.dev/vi/docs/reference/api/webhook-invoice-draft-created) | Hoá đơn nháp được tạo. |
| [`invoice.draft_updated`](https://hatang.dev/vi/docs/reference/api/webhook-invoice-draft-updated) | Hoá đơn nháp thay đổi. |
| [`invoice.draft_deleted`](https://hatang.dev/vi/docs/reference/api/webhook-invoice-draft-deleted) | Hoá đơn nháp bị xoá. |
| [`invoice.issued`](https://hatang.dev/vi/docs/reference/api/webhook-invoice-issued) | Nhà cung cấp đã phát hành hoá đơn điện tử. |
| [`invoice.tax_accepted`](https://hatang.dev/vi/docs/reference/api/webhook-invoice-tax-accepted) | Cơ quan thuế chấp nhận hoá đơn. |
| [`invoice.tax_rejected`](https://hatang.dev/vi/docs/reference/api/webhook-invoice-tax-rejected) | Cơ quan thuế từ chối hoá đơn. |
| [`invoice.canceled`](https://hatang.dev/vi/docs/reference/api/webhook-invoice-canceled) | Hoá đơn bị huỷ. |
| [`invoice.replaced`](https://hatang.dev/vi/docs/reference/api/webhook-invoice-replaced) | Hoá đơn được thay thế bằng hoá đơn mới. |
| [`invoice.adjusted`](https://hatang.dev/vi/docs/reference/api/webhook-invoice-adjusted) | Đã phát hành hoá đơn điều chỉnh. |
| [`invoice.failed`](https://hatang.dev/vi/docs/reference/api/webhook-invoice-failed) | Phát hành hoá đơn điện tử thất bại. |
| [`invoice.conflict`](https://hatang.dev/vi/docs/reference/api/webhook-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. |

Source: https://hatang.dev/vi/docs/reference/webhooks