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_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に設定できる値には下記の制限があります。

<https://> で始まっている
ドメイン名が国際化ドメインの場合は RFC3490 で定められたToASCIIの変換（4.1節）がおこなわれたドメイン名に変換済みである
RFC3986 にしたがって適切にエンコードされたURLである