HipChat APIのWebhooksについて
Webhook（Webフック）とは
Atlassian社のHipChatは仕事上のインスタントメッセージのやり取りに特化したアプリケーションサービスです。
JIRA, Confluence, GitHubからHipChatへの情報プッシュによる連携はよく知られていることですが、HipChatのWeb APIを利用すると逆も出来ます。 つまり、HipChatのルーム内でイベント（入退室、メッセージ、通知、トピック変更）があったとき、それを外部のサービスに知らせることが出来る、ということです。
これHipChatのAPIのWebhooksという機能を利用します。WebhookはHipChat APIのversion 2（現在ベータ版）で対応しています。HipChatのAPIはシンプルなREST 形式で認証用のトークンがあれば簡単に利用できます。
Webfookの利用手順としては下記の3ステップになります。このページではそれぞれのステップについて詳しく説明します。
- アカウント設定画面で認証用のトークンを発行
- Webhookを作成する
- 外部のサービスで情報を受け取る
1.の認証用トークンを既に持っている場合は1.の手順は不要です。API version 1でのグループ管理者によるトークンとは別のものなのでご注意を。
1. 認証用のトークンを発行
まずはHipChatのウェブサイトにいき、ログインしてアカウント設定画面にいきます。右上のAccount Settingから進みます。
アカウント設定画面の左メニューでAPI accessをクリック、再度パスワードを聞かれるので入力します。
まだトークンを作成していない場合は赤いCreate tokenボタンが表示されますのでそれをクリックします。
トークンができました、パチパチ。このトークンを利用するとそのユーザーの権限でAPIによるHipChatの操作ができてしまいますので、取り扱いには注意してください。
2. Webhookを作成する
HipChatのイベントが発生した際に外部サービスに通知するためのWebhookをAPIで作成します。現在HipChatでWebhookに対応しているイベントは指定したルームに対して
- 誰かが入室したとき (room_enter)
- 誰かが退室したとき (room_exit)
- メッセージが送られた時 (room_mesasge)
- 告知が送られてきた時 (room_notification)
- トピックが変更された時 (room_topic_change)
です。HipChatで上記のイベントが発生したときに、どういったデータ（Json形式）が送られてくるのかマニュアルに記載はありますが、実際にテストをして内容を見てみたいと思います。今回はメッセージのイベント送信のWebhookを作成します。
Webhookの作成にはCreate webhookというIFを利用します。リクエスト内容（ボディ）は以下になります。
- requset.json
{
"url" : "http://www.myservice.com/api/testhook.php",
"event" : "room_message",
"name" : "test_message_webhook"
} - url : HipChatでイベントが発生したとき（ここではメッセージがルームに送られた時）にWebhookがそのデータをPOSTする先のURL
- pattern : メッセージがこの正規表現にマッチした際のみ、データを送信（指定しなければすべて送る）
- event : HipChatのイベント検知のタイプ
- name : このWebhookの名前、任意でつけます
またリクエストの際にAPIのURLに下記のパラメータを追加します。
- ルーム名またはルームID - イベントを検知する対象ルームをパスパラメータとしてURL中に指定します。ここではテスト用のHipChatルーム、testroomを利用します。
- 認証用トークン(auth_token) - 1のて順で発行した認証用のトークン。クエリストリングとして追加します。
実際にcurlコマンドでWebhookを作成してみます。
作成されたWebhookのidとそのWebhookの情報取得のためのAPIのURL(Get Webhook)が返ってきました。成功です。
3. 外部のサービスで情報を受け取る
実際に先ほど作成したWebhookがどういったデータを外部のサービス（先ほどjsonの中で指定したURL）に渡しているのか見てみましょう。
先ほど指定したURLに下記のような簡単なスクリプトを設置します。外部から受け取ったリクエストの内容（ヘッダとボディ）をエラーログに出力する簡単なPHPスクリプトです。
<?php
$log_file = "/var/tmp/request.log";
$headers = getallheaders();
while (list ($header, $value) = each ($headers)) {
error_log("$header: $value\n", 3, $log_file);
}
error_log("\n", 3, $log_file);
$str = file_get_contents('php://input');
error_log($str, 3, $log_file);
error_log("\n", 3, $log_file);
?>
HipChatでWebhookを作成したルームでメッセージを送信してみます。
すると、上記のtesthook.phpにHipChatからアクセスがいきます。データ届きましたね！
- request.log
Host: www.myservice.com
User-Agent: HipChat.com
Content-Length: 630
Content-Type: application/json
connection: close
{
"event": "room_message",
"item": {
"message": {
"date": "2014-05-11T04:00:00+00:00",
"from": {
"id": 751596,
"links": {
"self": "https://api.hipchat.com/v2/user/751596"
},
"mention_name": "YumiNakajima",
"name": "Yumi Nakajima"
},
"id": "c9e9dde3-bef7-4600-969d-c7d7e8e88fb5",
"mentions": [],
"message": "HipChatでメッセージを送りました"
},
"room": {
"id": 559679,
"links": {
"self": "https://api.hipchat.com/v2/room/559679",
"webhooks": "https://api.hipchat.com/v2/room/559679/webhook"
},
"name": "testroom"
}
},
"oauth_client_id": "8add0238-4c72-4995-9bf1-7a91455f7de6",
"webhook_id": 31792
}
上記のようにHipChatで送信されたメッセージや、送信者、ルーム名が返されます。添付ファイルがある場合は、添付ファイルのURL、メンションがあればメンション名も入ります。
終わりに
HipChatでメッセージなどのイベント内容が他サービスに送れて何ができるの？と思いましたが、下記のようなことをすると面白いかもしれません
- HipChat上でメンションを入れたメッセージで、他人にタスク（Google Task, Asanaなど）をアサインする。例：
@TaoYamada このタスクお願いします
- HipChat上でサーバやサービスのオペレーションを実行する（対象ルームには適切なアクセス権限が必要かもしれません）：例
@ServiceServer01 deploy → ServiceServer01でデプロイ開始@ServiceServer01 monitor → 監視を開始、または監視結果を表示
Automate the Web - Zapierがこの機能をつかって、HipChatでのイベントから各種サービスへの連携を実現していますね。まだHipChat API version 2はベータ版ということですがいろいろ試してみると面白いと思います
