※本記事はアフィリエイト広告(PR)を含みます。
Webhookは、こちらから取りに行くのではなく向こうから届きます。外から届く経路を用意し、署名を検証して受け取ります。
作業場所はVMの中(Ubuntu Server)です。確認だけホストの Windows のブラウザから行います。
この記事に出てくるトークン・シークレット・URLは、すべてダミーです。 そのまま使っても動きません。自分で作った値を使ってください。そして、その値を記事・スクリーンショット・リポジトリに写さないでください。
ここまでで作ってきたものは、全部「聞かれたら答えるもの」でした。
APIの回で作ったのは、ブラウザが GET /api/books と聞きに来たら JSON を返すサーバーです。RESTの回で整えたのも、認証の回で守ったのも、全部その形です。
外のサービスのデータが欲しいときも、向きは同じでした。
こちらから
fetchして、返ってきたものを使う。
これが API を叩くということです。主導権はこちら側にあります。 欲しくなったときに聞きに行く。聞きに行かなければ何も起きない。
ところが、こういうものを作ろうとした瞬間に、この形が崩れます。
「リポジトリに Issue が立ったら、自動でコメントを付ける」 「メッセージが届いたら、5秒以内に返す」
いつ起きるか、こちらには分かりません。 1分後かもしれないし、3日後かもしれない。
素直にやるなら、1秒ごとに聞きに行くことになります。「新しいのある?」「無い」「新しいのある?」「無い」——これを24時間。99.99%が無駄で、しかも最悪1秒遅れます。 相手のサーバーからは、ただの迷惑な連打です。
だから、向きを逆にした仕組みがあります。
何かが起きたら、向こうがこちらの URL に POST してくる。
これが Webhook です。日本語で言えば「折り返し先」を先に登録しておく仕組みです。
そして、この向きの違いが、この記事の中身を全部決めます。
こちらから聞きに行くときは、相手が本物かどうかを HTTPS が保証してくれました。相手が誰かはこちらが決めていたからです。向こうから来るときは、そこが空っぽになります。
あなたの URL に POST してきたそれは、本当に相手のサービスですか。
URL を知っている人なら、誰でも同じ POST を送れます。 ここが山場です。
対象レベル: 中級 / 区分: 必修
この記事でわかること
- API と Webhook は「向き」だけが違うこと。その一点から、必要な対策が全部出てくること
- 自分のVMには、外から届かないこと。理由は NAT で、これは設定ミスではなく普通の状態だということ
- URL を知っていれば誰でも叩けること。だから署名の検証が「あったほうがいい」ではなく必須だということ
express.json()を通したあとでは、署名を検証できないこと。生のバイト列が要ること- 署名を
===で比べてはいけないこと(ハッシュの回と同じ理由) - 再送は障害ではなく仕様だということ。同じイベントが2回来る前提で書かないと、二重に実行されること
- 返事が遅いと、相手は「失敗した」と判断して送り直すこと。だから重い処理はキューへ回すこと
- Bot で難しいのは「反応させること」ではなく「反応させないこと」だということ
この記事でやること
- 自分のVMが外から届かないことを、コマンドで確かめる。 そのうえで通し方を3つ比べて、トンネルを選ぶ
POST /webhookを作る。 まずは受け取って200を返すだけの状態で、実際に届くところまで- 署名を自分で検証する。
crypto.createHmacとtimingSafeEqual。わざと失敗させて401を出す - 同じイベントをもう一度送って、処理が2回走るのを見る。 そのあと冪等に直す
- 返信する側を書く(外部APIを叩く・トークンは
.env・レート制限とリトライ)。最後に全部片づける
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| Webhook | 何かが起きたときに、相手のサーバーが、こちらの URL に POST してくる仕組み。 折り返し先を先に登録しておく |
| ペイロード | その POST の本文。 「何が起きたか」が JSON で入っている |
| エンドポイント | 受け口の URL。 この記事では https://(ドメイン)/webhook |
| HMAC | 秘密の値を混ぜて作るハッシュ。 同じ秘密を知っている人だけが、同じ値を作れる |
| 署名(シグネチャ) | 本文から HMAC で作った文字列。 相手がヘッダーに入れて送ってくる。こちらも自分で計算して、一致するか見る |
| 共有シークレット | 相手とこちらだけが知っている、署名を作るための秘密の文字列。 パスワードと同じ扱い |
| NAT | プライベートIPとグローバルIPを変換する仕組み。 家庭のルーターがやっている。中から外へは出られるが、外から中へは入れない |
| トンネル | 中から外へ接続を張っておき、外から来た通信をその接続に流し込む道具。 今回は ngrok |
| 冪等(べきとう) | 同じ操作を何回やっても、結果の状態が同じという性質。キューの回でも出てきました |
| 配信ID(デリバリーID) | その1回の POST に付く、重複しない番号。 再送しても同じ番号が付く。これが冪等化の鍵になる |
| レート制限 | 「一定時間にこれ以上叩くな」という上限。 超えると相手が 403 や 429 を返す |
① まず壁から — 外から自分のVMには届かない
手順から書きません。 ここを先に潰さないと、この記事は1行も進まないからです。
Webhook は「向こうがこちらに POST してくる」仕組みです。ということは、こちらに、外から到達できる URL が必要です。
あなたのVMには、それがありません。
なぜ届かないのか
Linuxのネットワークの回でやったことの回収です。VM の中で、自分のアドレスを見ます。
打つ場所: VM の中(Ubuntu)
出力の中に、こういう行があるはずです。
inet 192.168.245.130/24 brd 192.168.245.255 scope global ens33
192.168. で始まっています。 これはプライベートIPアドレスで、ネットワークの回で見たとおり、インターネット上には存在しないことになっているアドレスです。世界中の家庭とオフィスで、同じ番号が使い回されています。
次に、外から見たときの自分を見ます。
203.0.113.45
2つの数字が、まったく違います。
これが全部です。VM が外へ出るときは、VMware の NAT が住所を書き換え、さらに家庭のルーターがもう一度書き換えています。変換は2段かかっています。
そして NAT には、こういう性質があります。
中から外へ出た通信は、その返事だけが戻ってこられる。 外から突然来た通信は、誰に渡せばいいか分からないので、捨てられる。
ルーターは 203.0.113.45 に来た POST を、どのVMに渡せばいいか知りません。 そもそも、あなたの家には PC もスマホもテレビもいます。宛先を書く場所が無いのです。
これは壊れているのではありません。 むしろこれがあるから、家の中の機器が世界中から直接叩かれずに済んでいます。
さらに、契約によっては
203.0.113.45すら自分専用ではありません。 携帯回線や一部の光回線では、1つのグローバルIPを何百軒かで共有しています(CGNAT と呼ばれます)。この場合、あとで出てくる「ポート開放」は、そもそも選択肢に入りません。
通し方は3つある
| 手段 | やること | 良い点 | 悪い点 |
|---|---|---|---|
| トンネル | VMから外のサービスへ接続を張り、公開URLに来た通信をその接続に流し込んでもらう | ルーターを一切触らない。 数分で通る。やめるのはプロセスを止めるだけ | URLが毎回変わる(無料枠)。止め忘れると公開されっぱなし。第三者のサービスを経由する |
| VPSに置く | 最初からグローバルIPを持っている場所でアプリを動かす | 本番と同じ形。URLが固定。ドメインもHTTPSも普通に付けられる | 月額がかかる。 デプロイの作業が要る |
| ポート開放 | 家庭のルーターの設定で、外から来た通信を特定の機器へ転送する | 追加費用ゼロ | 家庭のネットワークが直接インターネットに晒される。 CGNATだと不可能。 IPは予告なく変わる |
家庭のルーターのポート開放は、学習目的では勧めません。
開けた瞬間から、世界中の自動スキャンが1日に何千回も叩きに来ます。 これは誇張ではなく、セキュリティの回でログを見たとおりの現実です。そして開けた穴の先には、あなたの家のネットワークがあります。
開けるなら「開けてよい場所」でやります。 それがVPSです。クラウドの選び方の回で見たとおり、壊れても困らない、家と繋がっていない場所を借りる、という意味です。
今回はトンネルを使う
理由は3つです。無料で始められる。ルーターを触らない。やめるのが一瞬。
ただし、割り切っている点をはっきりさせておきます。
- URLは起動のたびに変わります(無料枠の場合)。変わったら、相手側の登録URLも直す必要があります。 これは面倒ですが、「本番はこれではない」と体で分かるので、むしろ good です
- 無料枠には上限があります(同時トンネル数・月間の接続数など)。学習には十分ですが、常時稼働のサービスには使いません
- 開いている間、あなたのVMのポート3000は、URLを知っている人全員に公開されています。 使い終わったら必ず止めます。 これはこの記事の「後片づけ」の1番目です
本番に持っていくなら、この記事のコードをそのまま VPS に置きます。 デプロイの回でやったことがそのまま使えます。変わるのは「どうやって外から届かせるか」だけで、中身は1行も変わりません。
トンネルとは別の通し方として、はじめから外から届く IP を持つ VPS を 1 台借りる手もあります。さくらのVPS
は初期費用無料で、クレジットカード払いなら全プランを 2 週間無料で試せます(1GB プランは月払いで 880〜990 円・税込、2026-11 時点)。ただし解約しないと自動で本登録になり、お試し期間中は外向き通信が 10Mbps に制限される点は先に押さえておいてください。
② トンネルを通す
打つ場所: VM の中(Ubuntu)
ngrok version 3.18.4
snapで入らなかった場合は、ngrok の公式ドキュメントからLinux版を落としてください。中身は実行ファイル1つです。
次に、認証トークンを設定します。 ngrok のサイトで無料アカウントを作ると、ダッシュボードに表示されます。
上の文字列はダミーです。 自分のトークンに置き換えてください。 このコマンドは
~/.bash_historyに残ります。 秘密情報の回で見たとおりです。気になるなら、打ったあとに履歴から消してください。
では通します。 ポート3000を外に出します。
画面が切り替わって、こういう表示になります。
Session Status online
Forwarding https://a1b2c3d4.ngrok-free.app -> http://localhost:3000
Web Interface http://127.0.0.1:4040
Forwardingの行が、あなたの公開URLです。 この記事ではhttps://a1b2c3d4.ngrok-free.appと書きますが、あなたの値は違います。
この端末は、これで占領されます。 止めると URL も消えます。なので、以降の作業は別の端末(別のSSH接続)で行います。
Web Interfaceのhttp://127.0.0.1:4040は便利です。 VM の中のブラウザ、または VS Code のポート転送で開くと、届いた POST の中身がそのまま見られます。 署名がおかしいときに、ここで生の本文を確認できます。
[スクリーンショット: 01_ngrok起動.png] ngrok http 3000 を実行して Session Status: online と Forwarding の行が出ている画面を撮ってください。URL の部分は隠すか、撮ったあとで塗りつぶしてください。
③ 受け口を作る — まず200を返すだけ
いきなり署名検証を書きません。 「届いているのか、届いていないのか」だけを、先に確定させます。
打つ場所: VM の中(Ubuntu)
const express = require('express');
const app = express();
app.post('/webhook', express.json(), (req, res) => {
console.log('--- 届いた ---');
console.log('イベント:', req.headers['x-github-event']);
console.log('本文のキー:', Object.keys(req.body));
res.status(200).send('ok');
});
app.listen(3000, () => console.log('3000番で待機中'));
まず自分で叩いて、ここまでが正しいことを確かめます。 さらに別の端末を開いてください。
HTTP/1.1 200 OK
サーバー側の画面に 届いた が出ていれば、ここまでは正しいです。
相手側に登録する
この記事では、例として GitHub の Webhook を1つだけ使います。
理由は、GitHubの回ですでにアカウントとリポジトリを持っているからです。アプリの申請も、Botユーザーの作成も要りません。 そして GitHub には、同じ配信をもう一度送るボタンがあります。これが後半の主役になります。
他のサービスでも、やることは同じ3つです。 ①URLを登録する ②シークレットを決める ③届いたら署名を確かめる。 違うのはヘッダーの名前と、署名の作り方の細部だけです。 サービスの画面の手順は、そのサービスの公式ドキュメントを読んでください。この記事が扱うのは仕組みのほうです。
まず、共有シークレットを作ります。 手で考えません。
3f8a1c0d5e2b47a9c6d1e8f0a2b4c6d8e0f2a4b6c8d0e2f4a6b8c0d2e4f6a8b0
上の値はダミーです。 あなたの画面に出た値を使ってください。そして、この値をどこにも貼らないでください。
.env に入れます。秘密情報の回でやったとおりです。
WEBHOOK_SECRET=あなたが生成した値
node_modules/
.env
.gitignoreを先に書きます。 READMEの回で書いたとおり、git add .を一度でも打ってしまうと、履歴に残ります。
GitHub 側の設定は、リポジトリの Settings → Webhooks から行います。 入れる値は4つです。
| 項目 | 入れる値 |
|---|---|
| Payload URL | https://a1b2c3d4.ngrok-free.app/webhook(自分のURL + /webhook) |
| Content type | application/json |
| Secret | さっき生成した値 |
| 送るイベント | 「全部」を選ばない。 今回は Issues だけ |
イベントを「全部送る」にしないでください。 初回は動作確認をしたくて全部にしたくなりますが、push するたび・スターが付くたびに POST が飛んできます。 ログが埋まって、本当に見たいものが見えなくなります。必要なものだけ購読する、が原則です。
[スクリーンショット: 02_webhook登録.png] GitHub の Webhook 追加画面を撮ってください。Secret 欄と Payload URL は必ず隠してください。
登録すると、GitHub は確認のために ping イベントを1回送ります。 サーバー側の画面を見てください。
--- 届いた ---
イベント: ping
本文のキー: [ 'zen', 'hook_id', 'hook', 'repository', 'sender' ]
イベント: pingが出たら、外から自分のVMに届いています。 ここが、この記事で一番大きい山でした。
[スクリーンショット: 03_recent_deliveries.png] Webhook 設定画面の下部にある Recent Deliveries で、ping が緑のチェックになっている一覧を撮ってください。
④ 署名を検証する
いま作ったサーバーは、危険です。
なぜ危険なのか
URLを知っている人なら、誰でも同じ POST を送れます。
証明します。GitHub のふりをして、自分で叩いてみます。
HTTP/1.1 200 OK
通ります。 サーバー側にも 届いた と出ます。
HTTPS は「通信が盗み見られないこと」しか保証しません。 「送ってきたのが誰か」は、何も保証していません。
そして、この Bot はこのあと「Issue が立ったら、そのIssueにコメントする」動きをします。つまり偽の POST を送るだけで、他人が私のトークンを使ってコメントを書かせられるということです。
URL は秘密になりません。 ngrok の無料URLは推測しづらいですが、リンクを1回どこかに貼れば終わりです。 ブラウザの履歴にも、プロキシのログにも残ります。
だから「URLを秘密にする」は対策になりません。 本文そのものに、相手だけが作れる印を付けてもらいます。 それが署名です。
署名の正体は HMAC
ハッシュの回でやったハッシュに、秘密の値を混ぜたものが HMAC です。
相手は、本文と共有シークレットから HMAC を計算して、ヘッダーに入れて送ってくる。 こちらは、届いた本文と、自分が持っている同じシークレットから、もう一度計算する。 一致すれば、シークレットを知っている相手が送った本文だと分かる。
ポイントは「本文から作る」ところです。 本文を1文字でも書き換えると、値がまったく変わります。だから「相手が本物か」と「本文が途中で書き換わっていないか」が、同時に確かめられます。
GitHub の場合、ヘッダーはこの形で来ます。
X-Hub-Signature-256: sha256=8f1c2e...(64桁の16進数)
必ずハマる罠 — 生のボディが要る
素直に書くと、こうなります。
// ⚠️ これは動きません
app.post('/webhook', express.json(), (req, res) => {
const body = JSON.stringify(req.body);
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(body).digest('hex');
// ...
});
これは、必ず失敗します。 私は30分ここで溶かしました。
理由です。express.json() は、届いたバイト列を JSON として解釈して、JavaScript のオブジェクトに変換します。 そして JSON.stringify は、そのオブジェクトから新しく文字列を作り直します。
「同じ内容」ではありますが、「同じバイト列」ではありません。
改行が消え、インデントが消え、日本語のエスケープの仕方が変わることがあります。内容が同じでも、1バイト違えばハッシュはまったく別の値になります。
署名は「内容」ではなく「バイト列」に対して付いています。 だから、解釈する前の生のバイト列を、そのまま取っておかなければなりません。
Express でこれをやるには、そのルートだけ express.raw() を使います。
require('dotenv').config();
const express = require('express');
const crypto = require('crypto');
const app = express();
const SECRET = process.env.WEBHOOK_SECRET;
if (!SECRET) {
console.error('WEBHOOK_SECRET が設定されていません');
process.exit(1);
}
function isValidSignature(rawBody, header) {
if (!header) return false;
const expected =
'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
const a = Buffer.from(expected, 'utf8');
const b = Buffer.from(header, 'utf8');
if (a.length !== b.length) return false;
return crypto.timingSafeEqual(a, b);
}
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
const signature = req.headers['x-hub-signature-256'];
if (!isValidSignature(req.body, signature)) {
console.warn('署名が一致しません。捨てます');
return res.status(401).send('invalid signature');
}
const event = req.headers['x-github-event'];
const payload = JSON.parse(req.body.toString('utf8'));
console.log('署名OK:', event, payload.action || '');
res.status(200).send('ok');
});
app.listen(3000, () => console.log('3000番で待機中'));
変わった点は3つです。
express.json()→express.raw()。req.bodyがオブジェクトではなく Buffer(生のバイト列)になります- 検証を通ってから、自分で
JSON.parseする。順番が逆だと意味がありません - 検証に落ちたら
401を返して、何もしない
express.raw({ type: 'application/json' })のtypeを忘れないでください。 これが無いと、Content-Typeがapplication/jsonのリクエストは読み込まれず、req.bodyが Buffer になりません(Express 5 ではundefined、4 では空のオブジェクト)。署名の計算でTypeErrorになって 500 が返り、エラーの文面からは「typeを書き忘れた」と分からない、という一番つらい状態になります。
=== で比べない
上のコードで、なぜ expected === signature と書かなかったのか、という話です。
ハッシュの回で書いたことと、まったく同じ理由です。
JavaScript の === は、文字列を先頭から1文字ずつ比べて、違うところが見つかった瞬間に false を返します。 つまり——
先頭が違うときは、すぐ返る。 先頭10文字が合っていると、ほんの少しだけ長く時間がかかる。
その差はナノ秒ですが、何万回も測れば、平均には差が出ます。 攻撃する側は、1文字目を0からfまで総当たりして「一番遅かった文字」を採用する、を64回繰り返せば、署名を組み立てられます。これをタイミング攻撃と言います。
crypto.timingSafeEqual は、違いが見つかっても最後まで比べます。 だから時間から情報が漏れません。
timingSafeEqualは、長さが違う Buffer を渡すと例外を投げます。 だから上のコードでは、先にa.length !== b.lengthを見ています。 ここを忘れると、変なヘッダーを1回送られただけでサーバーが落ちます。 なお「長さが違う」ことは、この方式では隠す価値がありません(署名の長さは仕様で決まっているからです)。
動かして、両方を見る
サーバーを再起動します。まず、さっきの偽の POST をもう一度送ってみます。
HTTP/1.1 401 Unauthorized
invalid signature
弾けました。
次に、正しい署名を自分で作って通します。 手でやるのは大変なので、練習用のスクリプトを1本書きます。
// 練習用: 正しい署名を作る
require('dotenv').config();
const crypto = require('crypto');
const body = process.argv[2];
const sig =
'sha256=' + crypto.createHmac('sha256', process.env.WEBHOOK_SECRET).update(body).digest('hex');
console.log(sig);
HTTP/1.1 200 OK
ok
今度は通りました。 そして本文を1文字でも変えれば、また
401になります。 試してみてください。{"action":"opened"}を{"action":"Opened"}にするだけで落ちます。
最後に、本物で確かめます。 GitHub でリポジトリに Issue を1つ立ててください。
署名OK: issues opened
[スクリーンショット: 04_署名検証ログ.png] 401 が出ている行と、署名OK: issues opened が出ている行が、両方写っているサーバーの端末を撮ってください。
署名が保証しないもの
混同しやすいので、はっきりさせておきます。
| 署名が保証すること | 署名が保証しないこと |
|---|---|
| 送ってきた相手がシークレットを知っていること | その内容が事実であること |
| 本文が途中で書き換わっていないこと | 同じ本文が2回来ていないこと |
| — | その本文が「今」作られたものであること |
下2つは、このあとの⑤と⑥で自分でやります。
サービスによっては、署名にタイムスタンプを混ぜて「古い署名を弾けるようにしている」ものもあります(そのサービスの公式ドキュメントに書いてあります)。混ざっていない場合は、次に出てくる配信IDで重複を弾くことになります。
⑤ すぐ 200 を返す — 重い処理はキューへ
署名は通りました。次は返事の速さです。
Webhook を送る側は、こちらの返事を待っています。 そして、たいていのサービスには待つ上限があります。GitHub の場合は10秒です。
10秒返さないと、相手は「失敗した」と記録します。GitHub は自動では再送しませんが、自動で再送するサービスも多く、手動の Redeliver でも同じものが届きます。 そして、送り直します。
ここで、やりがちな書き方を見てください。
// ⚠️ これをやってはいけない
app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
if (!isValidSignature(req.body, req.headers['x-hub-signature-256'])) {
return res.status(401).send('invalid signature');
}
const payload = JSON.parse(req.body.toString('utf8'));
await postComment(payload); // ← 外部APIを叩く。何秒かかるか分からない
await saveToDatabase(payload); // ← DBに書く
res.status(200).send('ok');
});
動きます。動きますが、遅い日に壊れます。
GitHub の API がたまたま重かった。DBが詰まった。それだけで11秒かかり、相手はタイムアウトし、同じイベントをもう一度送ってきます。 そして2回目も11秒かかります。コメントは2つ付きます。
「たまに二重に実行される」バグの半分は、これです。 そして再現しません。 遅い日にしか起きないからです。
直し方は、キューの回でやったことと同じです。
受け取る。確かめる。積む。すぐ返す。処理は別で。
const jobs = [];
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
if (!isValidSignature(req.body, req.headers['x-hub-signature-256'])) {
return res.status(401).send('invalid signature');
}
jobs.push({
deliveryId: req.headers['x-github-delivery'],
event: req.headers['x-github-event'],
payload: JSON.parse(req.body.toString('utf8')),
});
res.status(202).send('accepted');
});
// 200ミリ秒ごとに1件ずつ処理する
setInterval(() => {
const job = jobs.shift();
if (job) {
handle(job).catch((err) => console.error('処理に失敗:', err.message));
}
}, 200);
受け口の中では、もう何もしていません。 署名を見て、積んで、返すだけです。これなら数ミリ秒です。
202 Acceptedは「受け取ったが、まだ終わっていない」という意味です。200でも構いませんが、202のほうが正直です。RESTの回で見た「ステータスコードで意味を伝える」の実例です。
この配列は、プロセスが落ちたら消えます。 学習用としては、これで十分です。 ただし「落としたら仕事が消える」ことは分かっておいてください。消えては困るようになったら、キューの回でやった本物のキューに置き換えます。 置き換える場所は
jobs.pushの1行だけです。
もう一つ、大事な判断があります。
署名の検証だけは、キューに積む前にやります。
積んでから確かめるのでは、偽物が積めてしまいます。 誰でも POST できる以上、キューは「叩けば無限に伸ばせる場所」になります。 検証は必ず入口です。
⑥ 冪等にする — 同じイベントが2回来る
ここが、Webhook で一番裏切られるところです。
再送は障害ではありません。仕様です。
送る側から見れば、当然の設計です。「返事が来なかった」ときに諦めたら、イベントが失われます。だから送り直します。 そして、返事が届かなかっただけで、こちらは既に処理を終えているかもしれません。
送る側には、区別がつきません。 だから「1回だけ届く」は、そもそも約束できないのです。
まず、2回走るところを見る
GitHub には、これを試すためのボタンがあります。 Webhook の設定画面 → Recent Deliveries → 該当の配信を開く → Redeliver。
押してください。 サーバーの画面に、まったく同じログがもう1行出ます。
そして、ヘッダーの配信IDを見てください。
署名OK: issues opened delivery=6f1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4a5b
署名OK: issues opened delivery=6f1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4a5b
配信IDが、まったく同じです。
これは偶然ではなく、こちらが重複を検知できるようにするための番号です。 X-GitHub-Delivery ヘッダーに入っています。多くのサービスに、同じ役割のヘッダーがあります。
[スクリーンショット: 05_redeliver.png] Recent Deliveries で Redeliver を押したあと、同じ配信が2行並んでいる画面を撮ってください。
受信済みのIDを覚える
const seen = new Map(); // 配信ID -> 受け取った時刻
const SEEN_LIMIT = 1000;
function isDuplicate(deliveryId) {
if (!deliveryId) return false;
if (seen.has(deliveryId)) return true;
seen.set(deliveryId, Date.now());
// 増えっぱなしにしない。古いものから捨てる
if (seen.size > SEEN_LIMIT) {
const oldest = seen.keys().next().value;
seen.delete(oldest);
}
return false;
}
受け口に1行足します。
const deliveryId = req.headers['x-github-delivery'];
if (isDuplicate(deliveryId)) {
console.log('受信済みなので捨てます:', deliveryId);
return res.status(200).send('already handled');
}
重複でも
200を返します。409などを返すと、相手は「失敗した」と受け取って、また送ってきます。 「もう終わっているので、送り直さなくていい」を伝えるのが目的なので、成功として返します。
もう一度 Redeliver を押してください。
受信済みなので捨てます: 6f1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4a5b
2回目は、何も起きなくなりました。
これでも足りない
正直に書きます。上の実装には穴があります。
| 穴 | 何が起きるか |
|---|---|
Map はメモリ上にある | 再起動すると全部忘れます。 直後に再送が来たら、二重に実行されます |
| 1000件を超えたら忘れる | 大量に来た日は、古い配信IDが押し出されます |
| プロセスが2つあると共有されない | キューの回で見たとおり、worker を増やした瞬間に破綻します |
本気でやるなら、置き場所を外に出します。
MySQLの回で作ったDBに、配信IDを
UNIQUE制約付きで INSERT する。 重複したら INSERT が失敗するので、そこで捨てる。
これが一番堅いやり方です。 Redisの回でやった SET key value NX EX 86400 でも同じことができます(こちらは期限を自動で切れるのが利点です)。
ただし、根本的な限界があります。 「処理を実行した」と「実行したと記録した」の間で落ちたら、どちらにしても取りこぼします。 これを完全に無くすことはできません。 だから最終的には「処理そのものを、2回やっても同じ結果になる形に書く」ほうが強いのです。それが冪等という言葉の本来の意味です。
⑦ 返信する側 — 外部APIを叩く
ここから先は、APIの回でやったことの裏返しです。 今度はこちらが叩く側になります。
トークンを用意する
GitHub にコメントを書くには、こちらが誰なのかを名乗る必要があります。 そのための文字列がアクセストークンです。
権限は、最小にします。
「全部にチェックを入れれば動く」で作ったトークンが漏れると、リポジトリを消せます。 今回必要なのは「Issue にコメントを書く」だけです。
GitHub の細かい発行手順は公式ドキュメントを見てください。選ぶのは、特定のリポジトリに限定した、Issues の書き込み権限だけです。
WEBHOOK_SECRET=あなたが生成した値
GITHUB_TOKEN=あなたのトークン
GITHUB_REPO=あなたのユーザー名/リポジトリ名
繰り返しますが、
.envは.gitignoreに入っていますか。 入れる前に一度でもgit add .したなら、READMEの回で書いたとおり、履歴に残っています。 その場合はトークンを作り直すのが唯一の対処です。
書き込む
async function postComment(issueNumber, text) {
const url = `https://api.github.com/repos/${process.env.GITHUB_REPO}/issues/${issueNumber}/comments`;
const res = await fetch(url, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
Accept: 'application/vnd.github+json',
'User-Agent': 'hitokoto-bot',
'Content-Type': 'application/json',
},
body: JSON.stringify({ body: text }),
});
if (!res.ok) {
const detail = await res.text();
throw new Error(`コメント投稿に失敗 ${res.status}: ${detail.slice(0, 200)}`);
}
return res.json();
}
そして、キューから呼ばれる handle を書きます。
async function handle(job) {
if (job.event !== 'issues') return;
if (job.payload.action !== 'opened') return;
const issue = job.payload.issue;
// ⚠️ Bot(GitHub App など)からのイベントには反応しない(無限ループ防止)
// 個人のトークンで書いた自分のコメントは sender.type が 'User' になるので、ここでは弾けない。
// この Bot は Issue の作成(opened)にしか反応しないので、自分のコメントでループはしない
if (job.payload.sender && job.payload.sender.type === 'Bot') return;
await postComment(issue.number, 'Issue を受け取りました。順番に見ます。');
console.log('コメントしました: #' + issue.number);
}
Issue を新しく立ててみてください。 数秒後、その Issue にコメントが付きます。
[スクリーンショット: 06_botのコメント.png] Bot が自動で付けたコメントが表示されている Issue の画面を撮ってください。
レート制限とリトライ
動いたので終わり、にはできません。
外部のAPIには必ず上限があります。 超えると、相手は 403 や 429 を返します。そして返事のヘッダーに、いつまで待てばいいかが書いてあります。
async function postCommentWithRetry(issueNumber, text, maxAttempts = 3) {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const res = await fetch(/* 略 */);
if (res.ok) return res.json();
// ⚠️ 4xx のうち、待っても直らないものは即やめる
if (res.status >= 400 && res.status < 500 && res.status !== 429) {
throw new Error(`直らないエラー ${res.status}`);
}
const retryAfter = Number(res.headers.get('retry-after'));
const waitMs = retryAfter ? retryAfter * 1000 : 1000 * Math.pow(2, attempt);
console.warn(`${res.status} なので ${waitMs}ms 待って再試行します`);
await new Promise((r) => setTimeout(r, waitMs));
}
throw new Error('リトライしても駄目でした');
}
3つ、原則があります。
| 原則 | 理由 |
|---|---|
| 4xx はリトライしない | トークンが無効・権限が無い・URLが違う。 何回叩いても同じです。叩くほど嫌われます |
| 待ち時間は倍にしていく | 一定間隔で叩き続けると、相手が復帰した瞬間に全員が殺到します。 サーキットブレーカの回でやった話です |
Retry-After があれば、それに従う | 相手が「これだけ待て」と言っているのに無視すると、上限が延長されることがあります |
監視の回を思い出してください。 リトライを黙って握り潰さないこと。 「動いているように見えるのに、実は毎回3回失敗してから成功している」状態は、ログに出ていないと絶対に気づけません。
⑧ Bot の設計 — 難しいのは「反応させない」ほう
技術的には、ここまでで完成しています。 ここからは設計の話です。そして、事故が起きるのはこちら側です。
反応する条件を、先に1つに絞る
作り始める前に、紙に1行で書きます。
「このBotは、◯◯のときだけ、△△をする」
この記事のBotなら「Issue が新しく立ったときだけ、受け取った旨をコメントする」です。
これを決めずに作ると、必ずこうなります。
- 全イベントを購読する → push のたびに動く
- 条件を書かない → Issue を編集しただけで、またコメントが付く
- 自分を除外しない → 自分のコメントに自分が反応して、無限にコメントする
3つ目は本当に起きます。 作らないものリストの回で「先に作らないものを決める」と書いたのは、まさにこういう場面のためです。
止め方を、作る前に決める
Bot を作るときの鉄則です。
「暴走したときに、どうやって止めるか」を、動かす前に決めておく。
止め方は3段階あります。上から順に速いです。
| 段階 | やること | かかる時間 |
|---|---|---|
| ①トンネルを止める | ngrok の端末で Ctrl+C | 1秒。届かなくなる |
| ②相手側で止める | Webhook 設定を Active から外す | 数十秒 |
| ③トークンを失効させる | GitHub の設定でトークンを削除 | 1分。書き込めなくなる |
①が一番速いのは、トンネルを使っているからです。 これはトンネルの、地味だが本当に大きい利点です。VPSに置いたら、この「電源を抜く」動作が遠くなります。
数を制限する
「1分あたり◯回まで」を、自分のBot側にも入れておきます。
let sentThisHour = 0;
setInterval(() => { sentThisHour = 0; }, 60 * 60 * 1000);
function canSend() {
if (sentThisHour >= 20) {
console.warn('1時間の上限に達しました。送信を止めます');
return false;
}
sentThisHour += 1;
return true;
}
相手のレート制限に頼らないでください。 相手の上限に当たるということは、そこまでは実際に送ってしまったということです。自分の上限は、自分で持ちます。
⑨ やってはいけないこと
動くようになったあとに、順に踏みやすいものです。
1. ペイロードを丸ごとログに出す
console.log(JSON.stringify(payload)); // ⚠️ やらない
Webhook のペイロードには、メールアドレス・ユーザー名・非公開リポジトリの中身・コミットメッセージが普通に入っています。それを標準出力に流すと、ログファイルに残り、ログ集約の回で外に送る設定にしていれば、そのまま外へ出ます。
出すのは「何が起きたか」だけにします。 イベント名・配信ID・対象の番号。中身は要りません。
デバッグ中にどうしても中身を見たいときは、ngrok の http://127.0.0.1:4040 を使ってください。 ファイルに残りません。
2. 無制限に返信する
Bot が荒らしになるのは一瞬です。 相手のサービスから見れば、あなたのトークンが不審な連投をしているだけです。アカウントごと止められます。
必ず「自分のBotの投稿には反応しない」と「1時間あたりの上限」を、両方入れてください。 片方だけでは足りません。
3. 利用規約と自動化のポリシーを読まない
これが一番あとから効きます。
ほとんどのサービスには、自動化について明文のルールがあります。 「Botには専用のアカウントを使え」「1秒あたり何回まで」「ユーザーに無断でDMを送るな」といった内容です。知らずに破っても、止められるときは止められます。
作り始める前に、そのサービスの開発者向け利用規約を読んでください。 5分です。
4. 個人のアカウントで動かす
Botは、専用のアカウントか、専用のアプリとして作ります。 自分のアカウントのトークンで動かすと、Bot が止められたとき、自分のアカウントごと止まります。
5. ngrok のURLを人に貼る
そのURLは、あなたのVMのポート3000そのものです。 署名検証があるので /webhook は安全ですが、他のパスを足していたら、そこは無防備です。
つまずいたところ
この記事を書きながら、実際に詰まった順です。
1. 署名が一度も一致しなかった(原因: express.json())
一番長く溶かしました。 シークレットを疑い、コピペミスを疑い、生成し直し、全部違いました。
原因は④に書いたとおり、express.json() を通したあとのオブジェクトから JSON.stringify して署名を計算していたことです。内容は同じでもバイト列が違うので、絶対に一致しません。
気づいたきっかけは、ngrok の
4040の画面で生の本文を見て、JSON.stringifyの結果と並べたことです。 文字数が違いました。
2. express.raw() にしたら、今度は body が空になった
express.raw() だけ書いて、{ type: 'application/json' } を書き忘れていました。req.body が Buffer にならず(Express 5 では undefined)、署名の計算で TypeError が出て 500 が返りました。 そしてエラーの文面には、type のことは何も書かれていません。
3. timingSafeEqual が例外を投げてサーバーが落ちた
適当なヘッダーを付けて curl した瞬間でした。長さが違う Buffer を渡すと例外になります。先に長さを見る1行を足して直りました。
この手のものは、「攻撃されたときに落ちる」形なので危険です。 受け口では、届いた値をすべて「壊れているかもしれないもの」として扱ってください。
4. ngrok を再起動したら、全部届かなくなった
Recent Deliveries が全部赤くなりました。 URLが変わったのに、GitHub 側の登録が古いままだったからです。
無料枠では、これは毎回起きます。 「昨日は動いたのに」の9割はこれです。 起動したら、まず Forwarding のURLを見る癖を付けてください。
5. Redeliver を押したら、コメントが2つ付いた
⑥をやる前です。 そして、このとき初めて「本番でも同じことが起きる」と分かりました。
重要なのは、これがバグではないことです。 送る側は仕様どおりに動いていて、壊れていたのはこちらの前提でした。
6. トンネルを開けたまま寝た
朝、ngrok の端末がまだ生きていました。 一晩中、私のVMのポート3000がインターネットに出ていたことになります。
何も起きませんでしたが、それは運です。 作業をやめるときに閉じる、を手順に入れました。 それが次の節です。
後片づけ
この記事は、外から届く口を開けています。必ず閉じてください。
① トンネルを止める(最優先)
ngrok を動かしている端末で Ctrl+C。
何も出なければ止まっています。 これが一番大事な1行です。
② 相手側の Webhook を消す
GitHub のリポジトリ → Settings → Webhooks → 該当のものを Delete。
残しておくと、GitHub は届かない相手に送り続け、しばらくすると勝手に無効化されます。 動作としては問題ありませんが、「登録したまま忘れる」が一番よくない状態です。
③ トークンを失効させる
練習で作ったトークンは、消します。
GitHub の Settings → Developer settings → Personal access tokens → Delete。
「あとで使うかもしれない」で残さないでください。 秘密情報の回で書いたとおり、「新しいのを作った」と「古いのを止めた」は別の作業です。残っているトークンは、生きている鍵です。
④ シークレットを捨てる
Webhook を消したので、このシークレットにはもう意味がありません。
⑤ Bot 本体を止める
node server.js を動かしている端末で Ctrl+C。 プロセスの回でやったとおり、systemd に登録していないので、これで完全に止まります。
⑥ 全部消したい場合
~/botを残しておくなら、.envが消えていることだけ確認してください。
まとめ — 理解できたこと
- API と Webhook の違いは「向き」だけ。 こちらから聞きに行くか、向こうから来るか
- 向きが変わると、HTTPS が保証してくれていたものが無くなる。 相手が誰かを、自分で確かめる必要が出てくる
- 自分のVMには外から届かない。 NAT で住所が2回書き換わっていて、戻る道が無いから。設定ミスではなく普通の状態
- 通し方は3つ。 トンネル / VPS / ポート開放。家庭のルーターのポート開放は勧めない(家のネットワークが直接晒される・CGNATだと不可能)
- 学習ではトンネル。 URLは毎回変わり、無料枠には上限があり、止め忘れると公開されっぱなし
- トンネルの地味な利点は「止めるのが1秒」。 暴走したときの電源が近い
- 最初は「受け取って
200を返すだけ」を作る。 届いているかどうかを先に確定させる - URLは秘密にならない。 知っていれば誰でも同じ POST を送れる。だから署名の検証は必須
- 署名の正体は HMAC。 本文と共有シークレットからハッシュを作る。 同じ秘密を知っている人だけが同じ値を作れる
express.json()のあとでは検証できない。 署名は「内容」ではなく「バイト列」に付いているexpress.raw({ type: 'application/json' })のtypeを省くと、body が空になる。 しかもエラーが出ない===で比べない。crypto.timingSafeEqualを使う。ハッシュの回と同じタイミング攻撃の話timingSafeEqualは長さが違うと例外を投げる。 先に長さを見る- 署名が保証するのは「相手が本物」と「本文が無改竄」だけ。 「事実か」「1回目か」「今のものか」は保証しない
- 返事が遅いと再送される。 10秒などの上限がある。重い処理は入口でやらない
- 受け口は「確かめる・積む・返す」だけにする。 署名の検証だけはキューに積む前(でないと偽物が積める)
202 Acceptedは「受け取ったが、まだ終わっていない」。 正直なコード- 再送は障害ではなく仕様。 送る側には「返事が届かなかった」と「処理されなかった」の区別がつかない
- 同じ配信には同じ配信IDが付く。 これで重複を弾く。Redeliver ボタンで自分で試せる
- 重複でも
200を返す。 エラーを返すと、また送られてくる - メモリで覚える冪等化は、再起動で忘れる。 本気なら DBに
UNIQUEで INSERT か Redis のNX - それでも「実行した」と「記録した」の間の穴は消えない。 最終的には処理そのものを冪等に書くほうが強い
- 返信する側はトークンで名乗る。 権限は最小に。
.envに置き、.gitignoreを先に書く - 4xx はリトライしない。 待っても直らない。叩くほど嫌われる
- 待ち時間は倍にしていく。
Retry-Afterがあればそれに従う - 相手のレート制限に頼らない。 当たった時点で、そこまでは送ってしまっている。自分の上限は自分で持つ
- Bot で難しいのは反応させることではなく、反応させないこと。 自分の投稿に反応させると無限ループする
- 購読するイベントを絞る。 「全部」を選ぶとログが埋まる
- 止め方を、動かす前に決めておく。 トンネルを止める → 登録を外す → トークンを失効
- ペイロードを丸ごとログに出さない。 メールアドレスも非公開リポの中身も入っている
- 利用規約と自動化ポリシーを、作る前に読む。 知らずに破っても止められる
- 個人のアカウントで動かさない。 Bot が止められると自分ごと止まる
- 後片づけの1番目はトンネルを止めること。 2番目は登録を消すこと。3番目はトークンを失効させること
参考リンク
- roadmap.sh — Backend Developer
- GitHub Docs — Webhooks
- GitHub Docs — Webhook の配信を検証する
- GitHub Docs — Webhook のヘッダー一覧
- GitHub Docs — Issue コメントの REST API
- GitHub Docs — REST API のレート制限
- GitHub Docs — パーソナルアクセストークンの管理
- Node.js 公式 — crypto モジュール
- Express 公式 — ミドルウェア一覧
- ngrok 公式ドキュメント
- cloudflared(Cloudflare のトンネル)
- RFC 2104 — HMAC の定義
- MDN — HTTP の解説
- RFC 6598 — CGNAT で使うアドレス帯
次に読む
この記事は 【第9段階】作品を1つ完成させる の 8 / 10 本目です。
| 記事 | |
|---|---|
| ← 前の記事 | 他人のページを書き換える — ブラウザ拡張を作る |
| → 次の記事 | スクレイピングは技術より先に線引き — 練習は自分のVMで |
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
作品づくり。Webhook で受ける形は roadmap.sh の項目ではない。

コメント