Webhook

Về ChatWork Webhook

ChatWork Webhook là function thông báo real time event như gửi message, edit, mention đến mình ở ChatRoom đang tham gia (GroupChat, DirectChat, MyChat) tới Webhook URL mà user đã setting.

Nhờ việc sử dụng ChatWork Webhook chúng ta không cần thiết gọi Chatwork API định kỳ (Polling) để kiểm soát event mà vẫn có thể nhận thông báo ở real time.

Vì có thể tạo function liên kết với service bên ngoài như tương tác Bot thao tác trên Chatwork một cách đơn giản nên nhất định bạn hãy thử sử dụng.

Có thể thiết lập Webhook URL từ Màn hình quản lý API

Request

Thông báo event từ ChatWork Webhook sẽ được tiến hành dựa vào request HTTPS POST tới Webhook URL đã được setting ở Màn hình quản lý Webhook. POST Request có cấu trúc như bên dưới.

Common request header

Field Name Value/description Sample
Content-Type application/json Content-Type: application/json
User-Agent ChatWork-Webhook/<version> User-Agent: ChatWork-Webhook/1.0.0
X-ChatWorkWebhookSignature Chữ ký dùng để Xác minh chữ ký request X-ChatWorkWebhookSignature: 5202BF4...B02772F

Common request body

Là JSON object có các mục bên dưới

Field Name Type Required Description
webhook_setting_id String Setting ID của Webhook thực hiện thông báo event
webhook_event_type String Các loại Webhook Event Object
webhook_event_time Value Thời gian event được ghi lại trên hệ thống ChatWork Webhook (epoch seconds)
webhook_event JSON Object Webhook Event Object tương thích với webhook_event_type

Sample request body

{
    "webhook_setting_id": "12345",
    "webhook_event_type": "mention_to_me",
    "webhook_event_time": 1498028130,
    "webhook_event":{
        "from_account_id": 123456,
        "to_account_id": 1484814,
        "room_id": 567890123,
        "message_id": "789012345",
        "body": "[To:1484814]Okazu là gì?",
        "send_time": 1498028125,
        "update_time": 0
    }
}

Response

  • Luôn trả về Status code 200 ở HTTP Request.
  • Dù HTTPS Request được thông báo từ ChatWork Webhook thất bại thì cũng không tiến hành gửi lại.
  • Size tối đa của response body là 512 bytes. Vượt quá giới hạn này sẽ bị lỗi.
  • Cần trả lời nội trong 10 giây ở HTTPS Request. Trường hợp vượt quá thì kết nối HTTPS sẽ bị ngắt và được xem như là error.
    • Gía trị 10 giây có thể sẽ thay đổi.
    • Tùy vào nội dung xử lý, nếu khó đoán chính xác thời gian trả lời thì nên xem xét phương pháp xử lý không đồng bộ thông qua Message queue.

Chức năng Failure Limit khi tỉ lệ báo lỗi gia tăng

Khi HTTPS POST Request bị lỗi do nguyên nhân nào đó, sẽ được xem như lỗi thông báo (notification error). Nếu tỉ lệ thông báo lỗi quá cao, ChatWork Webhook sẽ tự động thay đổi setting của Webhook tương ứng thành status “invalid”. Để active thì tự user cần phải thực hiện một cách rõ ràng. Các bước active xin hãy tham khảo màn hình edit của Webhook.

Xác minh chữ ký request

Để xác minh request được gửi từ nguồn ChatWork, mỗi lần request phải tiến hành kiểm tra chữ ký trên server user.

Các bước xác minh tiến hành như bên dưới.

  1. Lấy byte string đã decode BASE64 token làm secret key để lấy giá trị digest của request body dựa vào thuật toán HMAC-SHA256.
  2. Xác nhận string đã encode BASE64 giá trị digest đồng nhất với signature (Gía trị của X-ChatWorkWebhookSignature header) được cấp cho request header.

Có thể xác minh Token ở màn hình edit Webhook.

Webhook Event object

Tạo tin nhắn mới (webhook_event_type = "message_created")

Field Name Type Required Description
message_id String Message ID
room_id Value Chatroom ID mà message được gửi
account_id Value Account ID đã gửi message
body String Message text
send_time Value Thời gian gửi message(epoch seconds)
update_time Value Thời gian chỉnh sửa message lần cuối (epoch seconds)
Chú ý: Gía trị khi tạo message là 0

Sample của event object tạo tin nhắn:

{
    "message_id": "789012345",
    "room_id": 567890123,
    "account_id": 1484814,
    "body": "Đơn đặt hàng cho bữa trưa của quý khách đã hoàn tất.",
    "send_time": 1498028120,
    "update_time": 0
}

Chỉnh sửa tin nhắn (webhook_event_type = "message_updated")

Message edit event có cấu trúc giống với event Tạo tin nhắn.

Mention đến mình (webhook_event_type = "mention_to_me")

Field Name Type Required Description
from_account_id Value Acount ID thực hiện mention
to_account_id Value Acount ID của tài khoản được mention
room_id Value Chatroom ID mà ở đó phát sinh mention
message_id String Message ID mà ở đó user được mention
body String Text mesage mà ở đó user được mention
send_time Value Thời gian gửi message(epoch seconds)
update_time Value Thời gian edit message lần cuối (epoch seconds)
Chú ý: Gía trị khi tạo message là 0

Sample của event có mention đến mình:

{
    "from_account_id": 1234567890,
    "to_account_id": 1484814,
    "room_id": 567890123,
    "message_id": "789012345",
    "body": "[To:1484814]Okazu là gì?",
    "send_time": 1498028125,
    "update_time": 0
}

URL được thiết lập như một Webhook URL

Gía trị có thể thiết lập lên Webhook URL được giới hạn như sau:

  • Bắt đầu bằng https://
  • Nếu là tên domain quốc tế thì domain nó phải là domain đã được thực hiện chuyển đổi ToASCII (điều 4.1) được qui định tại RFC3490.
  • Là URL được encode tuân theo chuẩn RFC3986.