メインコンテンツへスキップ
アラートWebhookは、チームのアラートをお客様が所有するHTTPSエンドポイントに送信します。 オンコールツール、チケットキュー、または独自の運用ダッシュボードにアラートを連携する用途に利用できます。 アラートWebhookは認証Webhookとは別のものです。 認証Webhookは、セッション、エンティティ、取引の結果をアプリケーションに送信します。 アラートWebhookは、レビュー待ちの認証、失敗した支払い、サービス障害など、対応が必要な事象をチームに知らせます。 ペイロード、署名シークレット、署名、再試行スケジュールはいずれも認証Webhookとは別に用意されています。

送信先を設定する

アラートWebhookはAPIではなく、Business Consoleで設定します。 組織設定を管理できるメンバーは、送信先の追加、変更、テストを行えます。
1

送信先を追加する

組織設定 > チーム通知で、エンドポイントのURLを指定してアラートWebhookの送信先を追加します。 URLはhttps://を使用し、パブリックアドレスに解決される必要があります。
2

署名シークレットを保存する

Diditは、whsec_で始まる署名シークレットの全体を一度だけ表示します。 この時点で保存してください。以降、コンソールには末尾の4文字しか表示されません。
3

アラートをルーティングする

送信先を追加しただけでは、まだ何も送信されません。 受信したいアラートのルーティングルールに、この送信先を追加します。
4

テストを送信する

テスト送信をクリックしてalert.testアラートを送信し、エンドポイントがそれを受け付けることを確認します。
1つの組織につき、チーム通知に最大25件の送信先を登録できます。 送信先に届くのは本番環境のアクティビティのみです。 サンドボックスでの認証、法人確認、取引、AMLヒットに関するアラートが送信先に送られることはありません。

アラートの種類

ペイロード

すべてのアラートは、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のレスポンスを返すと、送信先は再接続が必要な状態になります(再試行を参照)。
アラートWebhookは、認証Webhookとは署名方法が異なります。 ヘッダー名は同じくX-Signature-V2ですが、署名対象の文字列が異なり、アラートWebhookではX-SignatureやX-Signature-Simpleは送信されません。 認証Webhook用の署名検証処理を再利用しないでください。

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には各配信とその結果が一覧表示され、失敗した配信をそこから再試行できます。

関連ページ

最終更新日 2026年11月1日