Webhook — Danh sách sự kiện
Chi tiết các loại sự kiện webhook (message, conversation, order, channel) và cấu trúc payload mẫu của mỗi loại.
Mọi payload webhook đều có khung chung: event_id, event_type, created_at và data. Phần data thay đổi theo từng loại sự kiện.
Các loại sự kiện
| event_type | Khi nào bắn |
|---|---|
message.created | Có tin nhắn mới (đến hoặc đi) trong một hội thoại |
message.updated | Tin nhắn bị sửa, ẩn hoặc thu hồi |
conversation.created | Hội thoại mới được mở |
conversation.updated | Thay đổi nhãn, người phụ trách, trạng thái đọc |
order.created | Đơn hàng mới được tạo từ hội thoại |
order.updated | Trạng thái / thông tin đơn hàng thay đổi |
channel.connected | Một kênh vừa được kết nối (connect status) |
channel.disconnected | Một kênh bị ngắt kết nối hoặc mất quyền |
post.created | Một bài viết mới được đăng trên kênh |
post.updated | Bài viết thay đổi nội dung hoặc đính kèm |
subscription.updated | Gói/đăng ký dịch vụ của workspace thay đổi (hạn mức, số kênh, gia hạn) |
Khung payload chung
Cấu trúc chung của mọi webhook
{
"event_id": "evt_01HZEVENT01",
"event_type": "message.created",
"created_at": "2026-10-31T09:35:01+07:00",
"data": { }
}Sự kiện message.created
message.created
{
"event_id": "evt_01HZEVENT01",
"event_type": "message.created",
"created_at": "2026-10-31T09:35:01+07:00",
"data": {
"message": {
"id": "msg_01HZIN0001",
"conversation_id": "cnv_01HZABCDEF",
"channel_id": "chn_01HZX8QWERTY",
"direction": "in",
"type": "text",
"text": "Shop cho mình hỏi còn hàng không ạ?",
"from": { "id": "cus_01HZCUST", "name": "Nguyen Van A" },
"sent_at": "2026-10-31T09:35:00+07:00"
}
}
}Sự kiện conversation.updated
conversation.updated
{
"event_id": "evt_01HZEVENT02",
"event_type": "conversation.updated",
"created_at": "2026-10-31T09:42:00+07:00",
"data": {
"conversation": {
"id": "cnv_01HZABCDEF",
"channel_id": "chn_01HZX8QWERTY",
"assignee_ids": ["usr_01HZNV01"],
"tags": ["can-tu-van", "da-chot-don"],
"unread": false,
"version": 7
}
}
}Sự kiện order.updated
order.updated
{
"event_id": "evt_01HZEVENT03",
"event_type": "order.updated",
"created_at": "2026-10-31T10:05:00+07:00",
"data": {
"order": {
"id": "ord_01HZORDER01",
"conversation_id": "cnv_01HZABCDEF",
"status": "confirmed",
"total_amount": 300000
}
}
}Sự kiện post.created / post.updated
post.updated
{
"event_id": "evt_01HZEVENT04",
"event_type": "post.updated",
"created_at": "2026-10-31T08:00:00+07:00",
"data": {
"post": {
"id": "pst_01HZPOST01",
"channel_id": "chn_01HZX8QWERTY",
"type": "livestream",
"message": "Live xả kho cuối tháng!",
"comment_count": 342
}
}
}Sự kiện channel.connected / channel.disconnected
channel.disconnected
{
"event_id": "evt_01HZEVENT05",
"event_type": "channel.disconnected",
"created_at": "2026-10-31T11:00:00+07:00",
"data": {
"channel": { "id": "chn_01HZX8QWERTY", "platform": "facebook", "connect_status": "disconnected" }
}
}Khi nhận
channel.disconnected, hãy cảnh báo người quản trị kết nối lại kênh — mọi lời gọi API tới kênh đó sẽ trả về CHANNEL_NOT_CONNECTED cho tới khi được cấp lại quyền.Sự kiện subscription.updated
subscription.updated
{
"event_id": "evt_01HZEVENT06",
"event_type": "subscription.updated",
"created_at": "2026-10-31T00:05:00+07:00",
"data": {
"subscription": {
"id": "sub_01HZSUB01",
"plan": "business",
"is_active": true,
"channel_quota": 20,
"channel_used": 7,
"renews_at": "2026-11-30T00:00:00+07:00"
}
}
}Với
conversation.updated, hãy dùng trường version (tăng dần) để bỏ qua các sự kiện đến trễ: chỉ áp dụng khi version lớn hơn giá trị bạn đã xử lý.Mọi payload webhook đều có khung chung: event_id, event_type, created_at và data. Phần data thay đổi theo từng loại sự kiện.
Các loại sự kiện
| event_type | Khi nào bắn |
|---|---|
message.created | Có tin nhắn mới (đến hoặc đi) trong một hội thoại |
message.updated | Tin nhắn bị sửa, ẩn hoặc thu hồi |
conversation.created | Hội thoại mới được mở |
conversation.updated | Thay đổi nhãn, người phụ trách, trạng thái đọc |
order.created | Đơn hàng mới được tạo từ hội thoại |
order.updated | Trạng thái / thông tin đơn hàng thay đổi |
channel.connected | Một kênh vừa được kết nối (connect status) |
channel.disconnected | Một kênh bị ngắt kết nối hoặc mất quyền |
post.created | Một bài viết mới được đăng trên kênh |
post.updated | Bài viết thay đổi nội dung hoặc đính kèm |
subscription.updated | Gói/đăng ký dịch vụ của workspace thay đổi (hạn mức, số kênh, gia hạn) |
Khung payload chung
Sự kiện message.created
Sự kiện conversation.updated
Sự kiện order.updated
Sự kiện post.created / post.updated
Sự kiện channel.connected / channel.disconnected
Khi nhận
channel.disconnected, hãy cảnh báo người quản trị kết nối lại kênh — mọi lời gọi API tới kênh đó sẽ trả về CHANNEL_NOT_CONNECTED cho tới khi được cấp lại quyền.Sự kiện subscription.updated
Với
conversation.updated, hãy dùng trường version (tăng dần) để bỏ qua các sự kiện đến trễ: chỉ áp dụng khi version lớn hơn giá trị bạn đã xử lý.Cấu trúc chung của mọi webhook
{
"event_id": "evt_01HZEVENT01",
"event_type": "message.created",
"created_at": "2026-10-31T09:35:01+07:00",
"data": { }
}message.created
{
"event_id": "evt_01HZEVENT01",
"event_type": "message.created",
"created_at": "2026-10-31T09:35:01+07:00",
"data": {
"message": {
"id": "msg_01HZIN0001",
"conversation_id": "cnv_01HZABCDEF",
"channel_id": "chn_01HZX8QWERTY",
"direction": "in",
"type": "text",
"text": "Shop cho mình hỏi còn hàng không ạ?",
"from": { "id": "cus_01HZCUST", "name": "Nguyen Van A" },
"sent_at": "2026-10-31T09:35:00+07:00"
}
}
}conversation.updated
{
"event_id": "evt_01HZEVENT02",
"event_type": "conversation.updated",
"created_at": "2026-10-31T09:42:00+07:00",
"data": {
"conversation": {
"id": "cnv_01HZABCDEF",
"channel_id": "chn_01HZX8QWERTY",
"assignee_ids": ["usr_01HZNV01"],
"tags": ["can-tu-van", "da-chot-don"],
"unread": false,
"version": 7
}
}
}order.updated
{
"event_id": "evt_01HZEVENT03",
"event_type": "order.updated",
"created_at": "2026-10-31T10:05:00+07:00",
"data": {
"order": {
"id": "ord_01HZORDER01",
"conversation_id": "cnv_01HZABCDEF",
"status": "confirmed",
"total_amount": 300000
}
}
}post.updated
{
"event_id": "evt_01HZEVENT04",
"event_type": "post.updated",
"created_at": "2026-10-31T08:00:00+07:00",
"data": {
"post": {
"id": "pst_01HZPOST01",
"channel_id": "chn_01HZX8QWERTY",
"type": "livestream",
"message": "Live xả kho cuối tháng!",
"comment_count": 342
}
}
}channel.disconnected
{
"event_id": "evt_01HZEVENT05",
"event_type": "channel.disconnected",
"created_at": "2026-10-31T11:00:00+07:00",
"data": {
"channel": { "id": "chn_01HZX8QWERTY", "platform": "facebook", "connect_status": "disconnected" }
}
}subscription.updated
{
"event_id": "evt_01HZEVENT06",
"event_type": "subscription.updated",
"created_at": "2026-10-31T00:05:00+07:00",
"data": {
"subscription": {
"id": "sub_01HZSUB01",
"plan": "business",
"is_active": true,
"channel_quota": 20,
"channel_used": 7,
"renews_at": "2026-11-30T00:00:00+07:00"
}
}
}