新規のお客様向けキャンペーン−20 %月払いなら最初の3か月が20%オフ料金プランを見る
SilentShield

Webhook が届かない

チャネル Webhook のアラートルールを作成したのに、サーバーに何も届きません。SilentShield がいつ Webhook を送信するのか、途中で何が妨げになるのかを説明します。

SilentShield が Webhook を送信するタイミング

Webhook を送信するのは、チャネルが Webhook になっている API キーのアラートルールだけです。SilentShield は 1 分に 1 回、有効なすべてのルールを確認します。条件が時間枠内で満たされると、「通知設定」ページに保存された Webhook URL へ POST リクエストを 1 回送信します。

原因

ルールが一度も発火していない

キーの「アラートルール」ページでは、「最終発火」列にルールが最後に発火した日時が表示されます。「なし」と表示されている場合、条件はまだ満たされておらず、何も送信されていません。しきい値と演算子を分析画面の数値と比べてください。

ルールが時間枠の経過を待っている

ルールが発火するのは時間枠(5m, 15m, 1h, 24h)ごとに最大 1 回です。発火後は、その時間枠が過ぎるまで再確認されません。24h のルールは 1 日に最大 1 回しか送信しません。

Webhook URL が保存されていない

ルールで選ぶのはチャネルだけで、アドレス自体は「通知設定」ページで保存します。アドレスがないとルールは発火しますが、何も送信されません。アドレスを保存できるのは、Webhook 連携を含むプランだけです。

アドレスにインターネットから到達できない

SilentShield は公開アドレスにのみ配信します。localhost、127.0.0.1、10.0.0.0/8、192.168.0.0/16、172.16.0.0/12 などのローカルや内部の宛先は、保存時と接続時に拒否されます。リダイレクトの後も同様です。ローカルでテストするには、公開 HTTPS アドレスを持つトンネルを使ってください。

サーバーの応答が遅すぎる

各試行で完全な応答を待つのは最大 5 秒です。すぐに 2xx ステータスで応答し、メッセージはその後でキューなどを使って処理してください。

サーバーがエラーまたはリダイレクトで応答している

配信済みとみなされるのはステータスコード 200~299 だけです。5xx、408、429 の後や接続に失敗した場合、SilentShield は 2 秒後と 8 秒後に再試行し、その後は諦めます。401、403、404 などのその他の 4xx は再試行しません。エンドポイントの前にあるファイアウォールやボット対策は 403 を返すことがよくあります。301、302、303 のリダイレクトの後はリクエストが本文なしの GET として続くため、最終的なアドレスを入力してください。

サーバー側で署名の検証に失敗する

シークレットを保存している場合、すべてのリクエストに X-Signature-256 ヘッダーが付きます。値は sha256= の後に本文の HMAC-SHA256 を 16 進数で続けたものです。JSON を解析する前に、届いたままの生の本文から計算してください。解析して書き直した本文では署名が変わります。シークレットがない場合、このヘッダーは付きません。

サーバーに届く内容

配信は次のようになります。X-Event-ID は同じ配信のすべての試行で変わりません。重複の検出に使ってください。

POST /your-webhook HTTP/1.1
Content-Type: application/json
X-Event-ID: 8b1f2c3d-4e5f-4a6b-9c7d-0e1f2a3b4c5d
X-Signature-256: sha256=<hex>

{
  "event_id": "8b1f2c3d-4e5f-4a6b-9c7d-0e1f2a3b4c5d",
  "alert_rule_id": "2a7c9e1b-3d4f-4b6a-8c0e-1f2a3b4c5d6e",
  "alert_name": "bot-rate",
  "api_key_id": "5c6d7e8f-9a0b-4c1d-8e2f-3a4b5c6d7e8f",
  "metric": "bot_rate",
  "operator": "gt",
  "threshold": 0.3,
  "value": 0.42,
  "fired_at": "2026-11-16T10:30:00Z"
}

署名を検証する

Node.js での例です。rawBody は変更していないリクエスト本文です。

const crypto = require("crypto");

function isValidSignature(rawBody, header, secret) {
  const expected = "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const received = header || "";
  return received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
}

// header = req.get("X-Signature-256")

ルールとチャネルの設定方法: アラートルール