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.

Xem Markdown

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_typeKhi nào bắn
message.createdCó tin nhắn mới (đến hoặc đi) trong một hội thoại
message.updatedTin nhắn bị sửa, ẩn hoặc thu hồi
conversation.createdHội thoại mới được mở
conversation.updatedThay đổ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.updatedTrạng thái / thông tin đơn hàng thay đổi
channel.connectedMột kênh vừa được kết nối (connect status)
channel.disconnectedMột kênh bị ngắt kết nối hoặc mất quyền
post.createdMột bài viết mới được đăng trên kênh
post.updatedBài viết thay đổi nội dung hoặc đính kèm
subscription.updatedGó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ý.