Webhook
Waroom で発生したイベント(インシデントの作成・更新など)を、任意の HTTPS エンドポイントへ HTTP POST で通知できます。このページでは、Webhook の送信先を追加してテスト配信で検証を完了するまでの手順を説明します。
送信されるリクエストの仕様・イベントの種類・リトライの挙動については Webhook イベントリファレンス を参照してください。
通知できるイベント
| イベント | 発生タイミング |
|---|---|
com.waroom.incident.incident.created | インシデントが作成されたとき |
com.waroom.incident.incident.updated | インシデントのステータス・重要度・インシデントコマンダーが変更されたとき |
com.waroom.incident.slack_channel.created | インシデント対応用の Slack チャネルが作成されたとき |
com.waroom.runbook.runbook.executed | ランブックのステップが完了になったとき |
com.waroom.runbook.runbook.skipped | ランブックのステップがスキップされたとき |
com.waroom.test.webhook.sent | テスト配信を実行したとき |
非公開インシデントに関するイベントは送信されません。
前提条件
- 受信エンドポイントの URL は HTTPS である必要があります(
http://の URL は登録できません) - 受信エンドポイントは 3 秒以内に 2xx 系のステータスコードを返してください。3 秒を超えるか 2xx 以外を返した場合、配信は失敗と判定されリトライされます
- 受信後の重い処理(データベースへの書き込み、外部 API の呼び出しなど)は、レスポンスを返した後に非同期で行うことを推奨します
設定手順
1. 受信エンドポイントを用意する
Waroom からの POST リクエストを受け取る HTTPS エンドポイントを用意します。まずは受信した JSON をログに出力して 200 を返すだけの実装で構いません。
2. 送信先を追加する
対象サービスのサービス設定を開き、「ウェブフックイベントの送信」セクションまでスクロールします。
「送信先」の「追加」をクリックすると、送信先の追加モーダルが開きます。
- 送信先名を入力します
- URL に手順 1 で用意したエンドポイントを入力します
- 「テスト配信」をオンにすると、追加と同時にテスト配信が送信されます
「追加する」をクリックします。
3. シークレットトークンを保存する
送信先を追加すると、シークレットトークンが表示されます。
シークレットトークンが表示されるのはこの画面だけです。 閉じる前に必ずコピーして、安全な場所に保存してください。
このトークンは、受信したリクエストが Waroom から送信されたものであることを検証する署名の鍵として使用します。検証方法は 署名を検証する を参照してください。
モーダルを閉じると、追加した送信先が一覧に「未検証」バッジ付きで表示されます。
4. テスト配信で検証する
追加直後の送信先は「未検証」状態です。テスト配信が成功すると「検証済み」になり、イベントが配信されるようになります。
手順 2 で「テスト配信」をオンにしていた場合は、追加時にテスト配信が送信されています。手動で送信する場合は、送信先のメニューから「テスト配信」を選択してください。
テスト配信ではイベント com.waroom.test.webhook.sent が送信されます。受信エンドポイントが 2xx を返すと、バッジが「未検証」から「検証済み」に変わります。
検証済みにならない場合は、以下を確認してください。
- 受信エンドポイントが 2xx を返しているか
- 3 秒以内にレスポンスを返しているか
- URL が正しいか、インターネットからアクセス可能か
5. 購読するイベントを選択する
送信先のメニューから「編集」を選択し、通知を受け取りたいイベントをオンにして「更新する」をクリックします。
以上で設定は完了です。選択したイベントが発生すると、登録した URL に通知が届きます。
送信先を管理する
編集する
送信先のメニューから「編集」を選択すると、送信先名・URL・購読イベントを変更できます。
トークンを再生成する
シークレットトークンを紛失した場合や漏洩の恐れがある場合は、送信先のメニューから「トークンを再生成」を選択してください。新しいシークレットトークンが表示されます。
トークンを再生成すると、送信先は「未検証」状態に戻り、イベントは配信されなくなります。新しいトークンを受信側に設定したうえで、再度テスト配信を実行して検証を完了してください。
削除する
送信先のメニューから「削除」を選択すると、その送信先へのイベント配信が停止します。
配信に失敗したとき
配信に失敗したイベントはリトライされます。すべてのリトライが失敗した場合は、配信履歴から手動で再送できます。
詳細は リトライと再送 を参照してください。