ブログ · · 約 10 分で
GitHub の Webhook の仕様:署名・10 秒のタイムアウト・再送なし・送信元 IP
GitHub の
要点
- GitHub は
失敗した Webhook を 自動では 再送しません。 失敗した 配信は、 管理画面か REST API から 過去 3 日分を 再配信できます。 - 応答に
10 秒以上 かかると 失敗と して 記録されます。 受け口では 10 秒以内に 2XX を 返し、 重い 処理は 後で 行います。 - 署名は
X-Hub-Signature-256 に sha256= と hex の HMAC-SHA256 で 入ります。 送信元 IP は meta API の hooks で 取れますが、 GitHub は IP での 許可を 勧めていません。
GitHub は、
仕様の一覧
| 項目 | 仕様 | 出典 |
|---|---|---|
| 署名の |
X-Hub-Signature-256sha256= と |
検証 |
| 旧来の |
X-Hub-Signature |
同上 |
| 署名の |
本文。 |
同上 |
| 応答の |
10 秒以内に |
推奨、 |
| 自動の |
なし | 失敗の |
| 手動の |
過去 3 日の |
再配信 |
| API での |
POST /repos/{owner}/{repo}/hooks/{hook_id}/deliveries/{delivery_id}/attempts |
REST API |
| 配信の |
X-GitHub-Delivery |
推奨 |
| 本文の |
25MB。 |
イベントと |
| 送信元 IP | https://api.github.com/meta のhooks。 |
GitHub の |
届くヘッダー
| ヘッダー | 中身 |
|---|---|
X-GitHub-Hook-ID |
Webhook の |
X-GitHub-Event |
配信を |
X-GitHub-Delivery |
配信を |
X-Hub-Signature-256 |
HMAC-SHA256 の |
X-Hub-Signature |
HMAC-SHA1 の |
User-Agent |
常にGitHub-Hookshot/ で |
X-GitHub-Hook-Installation-Target-Type |
Webhook を |
X-GitHub-Hook-Installation-Target-ID |
Webhook を |
GitHub は、X-GitHub-Event のaction を
署名の検証
X-Hub-Signature-256 はsha256= の
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyGithub(raw: Buffer, header: string, secret: string): boolean {
const expected = Buffer.from('sha256=' + createHmac('sha256', secret).update(raw).digest('hex'));
const got = Buffer.from(header);
return got.length === expected.length && timingSafeEqual(got, expected);
}GitHub はIt's a Secret to Everybody、Hello, World! のsha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17 です。
10 秒以内に返す受け口
GitHub のX-GitHub-Delivery での
X-GitHub-Delivery は
失敗した配信の定期的な再配信
自動の
- GitHub Actions の
ワークフローを 6 時間ごと (cron 20 */6 * * *)と 手動で 動かす。 - 前回の
実行時刻を リポジトリの 変数に 保存する。 初回は 実行の 24 時間前から 見る。 GET /repos/{owner}/{repo}/hooks/{hook_id}/deliveriesで配信の 一覧を 100 件ずつ取る。 - 配信を
guidでまとめ、 同じ guidの中に statusが"OK"のものが 1 つもなければ 失敗と みなす。 - 失敗した
guidごとに1 件だけ POST …/deliveries/{delivery_id}/attemptsで再配信する。
トークンは、GITHUB_TOKEN では
同じ
const base = `https://api.github.com/repos/${owner}/${repo}/hooks/${hookId}`;
const headers = { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json' };
const res = await fetch(`${base}/deliveries?per_page=100`, { headers });
const deliveries: { id: number; guid: string; status: string; delivered_at: string }[] = await res.json();
const byGuid = new Map<string, typeof deliveries>();
for (const d of deliveries) {
if (new Date(d.delivered_at) < since) continue; // 前回の実行より前のものは見ない
byGuid.set(d.guid, [...(byGuid.get(d.guid) ?? []), d]);
}
for (const [, group] of byGuid) {
if (group.some((d) => d.status === 'OK')) continue; // どれかが成功していれば済み
await fetch(`${base}/deliveries/${group[0]!.id}/attempts`, { method: 'POST', headers });
}再配信できるのは
送信元 IP で絞る場合
GitHub のhttps://api.github.com/meta のhooks に
- IP アドレスは
時々 変わる。 - IP での
許可は 勧めない。 使う 場合は API を 定期的に 確かめる ことを 強く 勧める。 - meta API の
一覧は 網羅的な ものではない。
また、
secret の切り替え
GitHub の
- 受け側を、
新旧 2 つの secret の どちらかで 合えば 通すように 変える。 - GitHub の
Webhook の 設定で secret を 新しい 値に 変える。 - 新しい
secret で 届く ことを 確かめてから、 受け側から 古い secret を 外す。
REST API で
自社が送る側になるとき
GitHub の
Webhook Admin は、webhook-id は
自社の
よくある質問
GitHub の Webhook は失敗しても再送されないのですか。
自動では
送信元 IP の一覧はどこにありますか。
https://api.github.com/meta の
secret を変えるときはどうすればよいですか。
Webhook の