Webhook で外部へ送る

Webhookは、akamineでできごとが起きたときに、指定したURLへ自動で知らせを送る仕組みです。自社のシステムや、ほかのサービスと連携したいときに使います。この記事では、送る設定と、受け取る側で署名を確かめる方法を説明します。

プロジェクトの設定を変えられる人（初期設定では、オーナーと管理者）が設定します。システム管理の「機能」で「外部通知」が無効になっていると、使えません。

画面の見方

プロジェクトの「設定」タブで、左のメニューの「Webhook」を開きます。画面は2つに分かれています。

• Webhookの購読: akamineから外へ送ります。
• 受信Webhook: 外からakamineへ送って、課題を作ります（受信メールから課題を作るも参照してください）。

送る設定を作る

1. 「購読を追加」を押します。
2. 送り先のURLを入れます。
3. 送りたいできごとを選びます。購読したできごとだけが、1件ずつ届きます。
4. 保存します。
5. 画面に表示される秘密鍵を控えます。

保存と送信のたびに、送り先のURLを安全面で検査します。社内ネットワークの内側のアドレスなど、公開されていない宛先は、登録できません。

選べるできごと

種類	できごと
課題	作成、更新、ステータスの変更、完了、移動、削除、復元
コメント	作成
マイルストーン	作成、更新、削除
ドキュメント	作成、更新、削除、復元

1つの操作で、複数のできごとが出ることがあります。たとえば課題を完了にすると、「更新」「ステータスの変更」「完了」の3つが出ます。ドキュメントの本文の自動保存は、5分に1回だけ「更新」として送られます。

テスト送信

設定ができたら、「テスト送信」を押すと、その場で1回送って結果を見られます。

送られる内容

本文はJSONです。主な項目は次のとおりです。

項目	内容
id	配信ID
event	できごとの種類（issue.created など）
occurred_at	起きた日時
project	プロジェクト
actor	操作した人
issue	課題
changes	変更前後の値（{項目: {from, to}}）

コメントやマイルストーンのできごとには、それぞれ comment と milestone が入ります。

署名を確かめる

届いた要求がakamineからのものか、確かめるために、次のヘッダーが付きます。

ヘッダー	内容
X-Akamine-Event	できごとの種類
X-Akamine-Delivery	配信ID（本文の id と同じ）
X-Akamine-Timestamp	送った時刻（Unix秒）
X-Akamine-Signature-V2	時刻つきの署名
X-Akamine-Signature	本文だけの署名（これまでの受け手のために残してあります）

受け取る側では、次の手順をおすすめします。

1. 秘密鍵を使い、{X-Akamine-Timestampの値}.{本文} のHMAC-SHA256を計算します。
2. 結果が X-Akamine-Signature-V2 の sha256= に続く値と一致するか確かめます。
3. X-Akamine-Timestamp が5分より古い要求は断ります。盗まれた要求を、あとから再送される被害を防げます。

失敗したとき

送信に失敗すると、1分後、5分後、30分後、2時間後、6時間後に再送します（最初の送信を含めて6回まで）。送信の記録は30日分残り、画面で中身、応答、結果を見られます。記録から、手動で再送することもできます。

非公開の課題のできごとは、Webhookには送られません。

関連する記事

• Slackと連携する
• 受信メールから課題を作る
• 公開APIとアクセストークン
• 自動化ルールを作る