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	string	◯	このイベントが通知される元になったWebhookの設定ID
webhook_event_type	string	◯	Webhookイベントオブジェクトの種類
webhook_event_time	integer	◯	Chatwork Webhookシステムにイベントが記録された時刻。Unix時間（秒）
webhook_event	object	◯	`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	string	◯	メッセージID
room_id	integer	◯	メッセージが送信されたチャットルームID
account_id	integer	◯	メッセージを送信したアカウントのID
body	string	◯	メッセージの本文
send_time	integer	◯	メッセージが投稿された時刻。Unix時間（秒）
update_time	integer	◯	メッセージが最後に更新された時刻。Unix時間（秒） ※ メッセージ投稿時の値は`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	integer	◯	メンション元アカウントのID
to_account_id	integer	◯	メンション先アカウント（自身のアカウント）のID
room_id	integer	◯	メンションが発生したチャットのルームID
message_id	string	◯	メンションが発生したメッセージのID
body	string	◯	メンションメッセージの本文
send_time	integer	◯	メッセージが投稿された時刻。Unix時間（秒）
update_time	integer	◯	メッセージが最後に更新された時刻。Unix時間（秒） ※ メッセージ投稿時の値は`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である