送信先を設定する
アラートWebhookはAPIではなく、Business Consoleで設定します。 組織設定を管理できるメンバーは、送信先の追加、変更、テストを行えます。1
送信先を追加する
組織設定 > チーム通知で、エンドポイントのURLを指定してアラートWebhookの送信先を追加します。
URLは
https://を使用し、パブリックアドレスに解決される必要があります。2
署名シークレットを保存する
Diditは、
whsec_で始まる署名シークレットの全体を一度だけ表示します。
この時点で保存してください。以降、コンソールには末尾の4文字しか表示されません。3
アラートをルーティングする
送信先を追加しただけでは、まだ何も送信されません。
受信したいアラートのルーティングルールに、この送信先を追加します。
4
テストを送信する
テスト送信をクリックして
alert.testアラートを送信し、エンドポイントがそれを受け付けることを確認します。アラートの種類
ペイロード
すべてのアラートは、JSONボディを持つPOSTリクエストです。
Diditは、キーをソートしたコンパクトなJSONとしてボディを送信します。
以下は読みやすく整形した例です。
dataには常に次のキーが含まれます。
event: イベントキー。例:session_in_review。labelとvalue: アラートの対象。例:Sessionと#1042。
dataにキーが追加されます。
alert.billing.autorefill_failedはpausedを追加します。これはブール値で、カードを更新するまで自動チャージが一時停止されている場合にtrueになります。alert.service.degradedとalert.service.recoveredは、service、status、incident_id、service_name、state、affected、country_name、started_at、resolved_at、duration_minutes、title、bodyを追加します。statusは、alert.service.degradedではdegradedまたはdown、alert.service.recoveredではrecoveredです。serviceはGET /v3/status/のサービスキーを使用し、incident_idはそこに含まれるインシデントのidと一致します。
webhook_typeの値やdataのキーは無視してください。そうすることで、新しい値やキーが追加されてもエンドポイントが動作し続けます。
リクエストヘッダー
署名を検証する
X-Signature-V2は、文字列<X-Timestamp>.<raw body>のHMAC-SHA256を16進数でエンコードした値で、送信先の署名シークレットをキーとして使用します。
- シークレットは、Diditが表示したとおり、
whsec_プレフィックスを含む全体をそのまま使用してください。 - 受信したままの生のリクエストバイト列に対して署名を計算してください。JSONをパースして再度シリアライズすると、バイト列が変わり、検証に失敗することがあります。
- 署名は定数時間で比較してください。
X-Timestampが自身のサーバーの時刻と5分を超えてずれているリクエストは拒否してください。Diditは再試行を含むすべての試行に新しいタイムスタンプで署名するため、この時間枠によって正当な再試行が拒否されることはありません。- 検証に失敗した場合は
400で応答してください。401、403、404、410のレスポンスを返すと、送信先は再接続が必要な状態になります(再試行を参照)。
Node.js (Express)
Python (Flask)
署名シークレットをローテーションする
署名シークレットのローテーションは、Team notificationsの送信先で行います。 Diditは新しいシークレットを一度だけ表示し、以降のすべての試行にそのシークレットで署名します。これにはローテーション前に作成されたアラートの再試行も含まれます。 古いシークレットは直ちに使用できなくなります。 移行期間はなく、以前のシークレットで作成された署名を含むヘッダーもありません。 シークレットをローテーションしたら、すぐに新しいシークレットをエンドポイントにデプロイしてください。再試行
Diditは、2xxのレスポンスをすべて配信成功として扱います。
各試行ではレスポンスを最大5秒間待機し、リダイレクトには従いません。
Diditは、タイムアウト、接続失敗、5xxレスポンス、または408、425、429のレスポンスの後にアラートを再試行します。
再試行は約24時間にわたり、最大5回行われます。
3xxやその他の4xxを含め、それ以外のレスポンスはすべて最終結果となります。
Send testで送ったテストは1回だけ試行され、再試行されることはありません。
401、403、404、410のレスポンスでも送信先は再接続が必要な状態になり、コンソールではReconnectステータスとして表示されます。
Diditの送信時に、URLがプライベートアドレスやその他のブロックされているアドレスに解決される場合も同様です。
Diditはその送信先に引き続き新しいアラートを送信し、次に配信が成功するか、URLを更新すると、送信先は再びアクティブになります。
Team notificationsのRecent notificationsには各配信とその結果が一覧表示され、失敗した配信をそこから再試行できます。