Webhook

ChatWork Webhookについて

ChatWork Webhookは、参加するチャットルーム(グループチャット、ダイレクトチャット、マイチャット)での、メッセージの送信・編集、自分へのメンションといったイベントを、ユーザーが設定したWebhook URLにリアルタイムに通知する機能です。

ChatWork Webhookを利用することで、チャットワークAPIを定期的に呼び出して(ポーリングして)イベント検出をおこなう必要がなく、リアルタイムに通知を受け取ることができるようになります。

チャットワーク上で動作する対話型Botのような外部サービスと連携する機能を、簡単に作成できるようになりますので、ぜひご活用ください。

Webhook URLはAPI管理画面から設定が可能です。

リクエスト

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: 5202BF4...B02772F

共通リクエストボディ

下記の項目を持つ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リクエストは失敗しても、再送はおこなわれません。
  • レスポンスボディのサイズ上限は512バイトです。これを超えた場合、エラーとして扱われます。
  • HTTPSリクエストには 10 秒以内に応答する必要があります。超過した場合、HTTPS接続が切断され、エラーとして扱われます。
    • 10 秒という値は変更される可能性があります。
    • 処理内容によって応答時間の予測が難しい場合、メッセージキューを介した非同期処理方式の検討をおすすめします。

通知エラーレート上昇時のFailure Limit機能について

HTTPS POSTリクエストが何らかの原因でエラーになった場合、通知エラーとして扱われます。通知エラーレートが高くなった場合、ChatWork Webhookは該当するWebhookの設定を自動で「無効」のステータスに変更します。有効化はユーザー自身で明示的におこなう必要があります。有効化の操作に関してはWebhook編集画面をご覧ください。

リクエストの署名検証

リクエストの送信元がチャットワークであることを確認するために、リクエストごとにユーザーのサーバで署名検証をおこなわなくてはなりません。

検証は以下の手順でおこないます。

  1. トークンをBASE64デコードしたバイト列を秘密鍵として、HMAC-SHA256アルゴリズムによりリクエストボディのダイジェスト値を得ます
  2. ダイジェスト値をBASE64エンコードした文字列が、リクエストヘッダに付与されたsignature(X-ChatWorkWebhookSignatureヘッダの値)と一致することを確認します

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

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