Webhookについて
Chatwork Webhookは、参加するチャットルーム(グループチャット、ダイレクトチャット、マイチャット)での、メッセージの送信・編集、自分へのメンションといったイベントを、ユーザーが設定したWebhook URLにリアルタイムに通知する機能です。
Chatwork Webhookを利用することで、Chatwork APIを定期的に呼び出して(ポーリングして)イベント検出をおこなう必要がなく、リアルタイムに通知を受け取ることができるようになります。
Chatwork上で動作する対話型Botのような外部サービスと連携する機能を、簡単に作成できるようになりますので、ぜひご活用ください。
Webhook URLは API管理画面 から設定が可能です。
※ 1アカウントあたり5件までWebhookの設定が可能です。
リクエスト
Chatwork Webhookによるイベント通知は、Webhook管理画面 で設定されたWebhook URLにHTTPS POSTリクエストをすることによっておこなわれます。POSTリクエストは下記の構造を持ちます。
共通リクエストヘッダ
フィールド名 | 値/説明 | サンプル |
---|---|---|
content-type | application/json | content-type: application/json |
user-agent | ChatWork-Webhook/<version> | user-agent: ChatWork-Webhook/1.0.0 |
x-chatworkwebhooksignature | リクエストの署名検証 に使うための署名 | x-chatworkwebhooksignature: G7Gt...yLQk= |
共通リクエストパラメータ
キー名 | 値/説明 | サンプル |
---|---|---|
chatwork_webhook_signature | リクエストの署名検証 に使うための署名 共通リクエストヘッダの x-chatworkwebhooksignature と同じ内容 | chatwork_webhook_signature= G7Gt...yLQk%3d |
共通リクエストボディ
下記の項目を持つJSONオブジェクトです。
フィールド名 | タイプ | 必須 | 説明 |
---|---|---|---|
webhook_setting_id | 文字列 | ◯ | このイベントが通知される元になったWebhookの設定ID |
webhook_event_type | 文字列 | ◯ | Webhookイベントオブジェクト の種類 |
webhook_event_time | 数値 | ◯ | Chatwork Webhookシステムにイベントが記録された時刻(エポック秒) |
webhook_event | JSONオブジェクト | ◯ | webhook_event_typeに応じた Webhookイベントオブジェクト |
リクエストボディのサンプル
{
"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]おかずはなんですか?",
"send_time": 1498028125,
"update_time": 0
}
}
レスポンス
- HTTPSリクエストには常にステータスコード200を返してください。
- Chatwork Webhookから通知されるHTTPS POSTリクエストは失敗しても、再送はおこなわれません。
- レスポンスボディのサイズ上限は2,048バイトです。これを超えた場合、エラーとして扱われます。
- HTTPSリクエストには10秒以内に応答する必要があります。超過した場合、HTTPS接続が切断され、エラーとして扱われます。
- 10秒という値は変更される可能性があります。
- 処理内容によって応答時間の予測が難しい場合、メッセージキューを介した非同期処理方式の検討をおすすめします。
通知エラーレート上昇時のFailure Limit機能について
HTTPS POSTリクエストが何らかの原因でエラーになった場合、通知エラーとして扱われます。通知エラーレートが高くなった場合、Chatwork Webhookは該当するWebhookの設定を自動で「無効」のステータスに変更します。有効化はユーザー自身で明示的におこなう必要があります。有効化の操作に関してはWebhook編集画面をご覧ください。
リクエストの署名検証
リクエストの送信元がChatworkであることを確認するために、リクエストごとにユーザーのサーバで署名検証をおこなわなくてはなりません。
検証は以下の手順でおこないます。
- トークンをBase64デコードしたバイト列を秘密鍵とします(トークンはWebhook編集画面で確認できます)
- ChatworkのWebhookからのHTTPSリクエストボディをそのままの文字列で取得します
- 取得したHTTPSリクエストボディと秘密鍵をつかって、HMAC-SHA256アルゴリズムによりダイジェスト値を取得します
- ダイジェスト値をBase64エンコードした文字列が、リクエストヘッダに付与された署名(
x-chatworkwebhooksignature
ヘッダ、もしくはリクエストパラメータchatwork_webhook_signature
の値)と一致することを確認します
トークンはWebhook編集画面で確認できます。
Webhookイベントオブジェクト
メッセージ作成(webhook_event_type = "message_created")
フィールド名 | タイプ | 必須 | 説明 |
---|---|---|---|
message_id | 文字列 | ◯ | メッセージID |
room_id | 数値 | ◯ | メッセージが送信されたチャットルームID |
account_id | 数値 | ◯ | メッセージを送信したアカウントID |
body | 文字列 | ◯ | メッセージ本文 |
send_time | 数値 | ◯ | メッセージの送信時刻(エポック秒) |
update_time | 数値 | ◯ | メッセージの最終編集時刻(エポック秒) 注:メッセージ作成時の値は0 |
メッセージ作成イベントオブジェクトのサンプル:
{
"message_id": "789012345",
"room_id": 567890123,
"account_id": 1484814,
"body": "お客様とのランチミーティング用のお弁当、発注完了しました。",
"send_time": 1498028120,
"update_time": 0
}
メッセージ編集(webhook_event_type = "message_updated")
メッセージ編集イベントは メッセージ作成 イベントと同じ構造を持ちます。
自分へのメンション(webhook_event_type = "mention_to_me")
フィールド名 | タイプ | 必須 | 説明 |
---|---|---|---|
from_account_id | 数値 | ◯ | メンション元のアカウントID |
to_account_id | 数値 | ◯ | メンション先のアカウントID |
room_id | 数値 | ◯ | メンションが発生したチャットルームID |
message_id | 文字列 | ◯ | メンションが発生したメッセージID |
body | 文字列 | ◯ | メンションメッセージ本文 |
send_time | 数値 | ◯ | メッセージの送信時刻(エポック秒) |
update_time | 数値 | ◯ | メッセージの最終編集時刻(エポック秒) 注:メッセージ作成時の値は0 |
自分へのメンションイベントのサンプル:
{
"from_account_id": 1234567890,
"to_account_id": 1484814,
"room_id": 567890123,
"message_id": "789012345",
"body": "[To:1484814]おかずはなんですか?",
"send_time": 1498028125,
"update_time": 0
}
Webhook URLとして設定できるURL
Webhook URLに設定できる値には下記の制限があります。
Updated over 2 years ago