Discord webhook の死活監視と自動修復

通知用の Discord webhook は、Discord 側で削除されると 例外を投げずに 404 を返すだけになる。送信側が戻り値を捨てていると通知は無言で止まり、誰も気づかない。この指示書は「死んだら翌日に自動で直る」状態を作る。

解決する実害

実際に起きた事故（一次情報）:

• webhook が削除され HTTP 404 / {"message":"Unknown Webhook","code":10015} を返すようになった
• しかし複数の設定ファイルがその URL をコピーで持っていたため、日次のコスト通知が6日間止まっていたのに誰も気づかなかった
• 同じチャンネルには別名の代替 webhook が既に存在していた。つまり機械的に復旧できたのに、人が気づくまで放置された

根本原因は「webhook URL が N 箇所にコピーされている」構造。1本死ぬと複数の通知系が同時に、かつ無言で停止する。

設計（4点セット）

1. 台帳を先に作る — これが最重要

死んだ webhook からは channel_id を取得できない（404 は本文を返さない）。だから「生きているうちに」チャンネル対応を記録しておかないと、後から復旧先を機械判定できない。

生存確認に成功したとき、必ず次を保存する:

{
  "<webhookId>": {
    "channelId": "<チャンネルID>",
    "channelName": "<webhook名>",
    "files": ["<この webhook を参照している設定ファイルの絶対パス>"],
    "lastSeenAliveAt": "<ISO8601>"
  }
}

token は台帳に保存しない。 ID とチャンネルだけで復旧判定は成立する。

2. 死活確認には User-Agent を必ず付ける

webhook URL そのものに GET すると、投稿せずにメタ情報（channel_id / name）だけ取れる（存在確認に最適）。

ただし User-Agent ヘッダが無いと Cloudflare が 429 / error code 1015 を返す。これは実行環境によって発生し、「webhook は生きているのに死んでいると誤判定する」原因になる。次の形式を付ける:

User-Agent: DiscordBot (<自社サイトURL>, 1.0) <アプリ名>

補足: 429 でも 1015 は IP レベルのブロックなので即リトライしても無駄。それ以外の 429 だけ数秒待って1回だけ再送する。

3. 自動修復は「同一チャンネルのときだけ」

死んだ webhook について、台帳から channelId を引き、同じ channelId を持つ生存 webhook が見つかったときに限り、設定ファイル内の URL を置換する。

• 置換前に <file>.bak-YYYY-MM-DD を作る
• channelId が不明、または同一チャンネルの生存 webhook が無ければ 置換せず「要手動」として報告する
• チャンネルが一致しない webhook で代替してはいけない（別チャンネルへ誤送信する事故になる）

4. 通知先は「生きている webhook」

死亡を知らせる通知を、死んだ webhook 自身へ送っては意味がない。台帳で最も新しく生存確認できた webhook へ送る。本文に入れるのは:

• 死んだ webhook の ID（token は絶対に出さない）
• それを参照している設定ファイルのフルパス
• 自動修復したか、要手動か

実装の要件

CLI として次を持たせる:

フラグ	挙動
（なし）	死活確認し、台帳を更新し、死亡があれば通知
--fix	上記に加えて同一チャンネル条件での自動置換を行う
--dry-run	送信も置換もしない（台帳更新も行わない設計にするなら、別途 dry-run なしの定期実行が必要）
--scan <path>	走査対象を追加
--json	機械可読な結果を stdout へ

走査対象は設定ファイルの置き場だけにする。ログやセッション履歴が入るディレクトリを再帰的に走査すると、巨大ファイルを読んで極端に遅くなる。

抽出の正規表現:

/https:\/\/discord\.com\/api\/webhooks\/(\d{15,})\/([A-Za-z0-9_-]{40,})/g

終了コードは「死亡があり、かつ自動修復できなかったものが残る」場合のみ非ゼロにする。監視ジョブがそれを拾えるようにするため。

定期実行に載せる

日次で1回動けば十分（webhook はそう頻繁に消えない）。既存の起動フック／スケジューラから、前回実行から20時間以上経っていれば起動する形にする。ガードファイルの mtime で判定するのが簡単。

これがあれば「死んでから気づくまで6日」が「翌日に自動修復」になる。

テスト（ネットワークに出さない）

次の4点を単体テストで固定する。実 API を叩かずに書ける。

1. 正規表現が webhook URL を正しく抽出する
2. 台帳マージで token が保存されない
3. 置換候補が同一チャンネルの生存 webhook に限られる
4. ログ用マスク処理が token を一切残さない

よくある落とし穴

• 送信関数が真偽値しか返していない — catch { return false } で握り潰していると、404 なのか 429 なのかネットワーク断なのか永久に分からない。{ sent, code, reason } を返し、呼び出し元の結果に載せる
• 「webhook を GET したら投稿されてしまう」と思って確認を避ける — GET は投稿しない。存在確認に安全に使える
• 表示名が古い webhook 名に引きずられる — 投稿ペイロードの username で上書きできる
• チャンネル特定を人の記憶に頼る — 台帳が無いと、死んだ後に「これはどこ宛だったか」が分からなくなる

完了の判定

• テストが通る
• 実環境で --dry-run を実行し alive=N dead=0 を確認
• 台帳ファイルが生成され、token が含まれていないことを目視で確認
• 実際の通知系（日次レポート等）を1回強制実行し、受信側チャンネルに届いたことを確認する。送信関数の戻り値だけで完了としない