# 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 は本文を返さない）。だから「生きているうちに」チャンネル対応を記録しておかないと、後から復旧先を機械判定できない。 生存確認に成功したとき、必ず次を保存する: ```json { "": { "channelId": "<チャンネルID>", "channelName": "", "files": ["<この webhook を参照している設定ファイルの絶対パス>"], "lastSeenAliveAt": "" } } ``` **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 を置換する。 - 置換前に `.bak-YYYY-MM-DD` を作る - `channelId` が不明、または同一チャンネルの生存 webhook が無ければ **置換せず「要手動」として報告**する - **チャンネルが一致しない webhook で代替してはいけない**（別チャンネルへ誤送信する事故になる） ### 4. 通知先は「生きている webhook」 死亡を知らせる通知を、死んだ webhook 自身へ送っては意味がない。台帳で最も新しく生存確認できた webhook へ送る。本文に入れるのは: - 死んだ webhook の **ID**（token は絶対に出さない） - それを参照している**設定ファイルのフルパス** - 自動修復したか、要手動か ## 実装の要件 CLI として次を持たせる: | フラグ | 挙動 | |---|---| | （なし） | 死活確認し、台帳を更新し、死亡があれば通知 | | `--fix` | 上記に加えて同一チャンネル条件での自動置換を行う | | `--dry-run` | 送信も置換もしない（**台帳更新も行わない設計にするなら、別途 dry-run なしの定期実行が必要**） | | `--scan ` | 走査対象を追加 | | `--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回強制実行し、**受信側チャンネルに届いたことを確認**する。送信関数の戻り値だけで完了としない ---