ブログ · · 約 10 分で読めます

GitHub の Webhook の仕様:署名・10 秒のタイムアウト・再送なし・送信元 IP

GitHub の Webhook の署名(X-Hub-Signature-256)、10 秒のタイムアウト、自動の再送がないことと再配信、失敗した配信を拾うスクリプト、meta API の送信元 IP を公式で確かめてまとめます。

要点

  • GitHub は失敗した Webhook を自動では再送しません。失敗した配信は、管理画面か REST API から過去 3 日分を再配信できます。
  • 応答に 10 秒以上かかると失敗として記録されます。受け口では 10 秒以内に 2XX を返し、重い処理は後で行います。
  • 署名は X-Hub-Signature-256 に sha256= と hex の HMAC-SHA256 で入ります。送信元 IP は meta API の hooks で取れますが、GitHub は IP での許可を勧めていません。

GitHub は、失敗した Webhook の配信を自動では再送しません。受け口が落ちていた間の配信は、管理画面か REST API から再配信する必要があり、対象は過去 3 日分です。応答に 10 秒以上かかった配信も失敗として記録されます。この記事では、2026-09-27 に GitHub の公式のドキュメントで確かめた仕様を表にまとめ、失敗した配信を定期的に拾って再配信する方法と、送信元 IP の扱いを書きます。

仕様の一覧

項目 仕様 出典
署名のヘッダー X-Hub-Signature-256(sha256= と hex)。secret を設定したときだけ付く 検証
旧来の署名 X-Hub-Signature(SHA-1)。互換のためだけに残されている 同上
署名の対象 本文。UTF-8 として扱う 同上
応答の期限 10 秒以内に 2XX を返す。10 秒を超えると失敗として記録 推奨、失敗の扱い
自動の再送 なし 失敗の扱い
手動の再配信 過去 3 日の配信。リポジトリの Webhook は管理者、組織の Webhook は組織の owner 再配信
API での再配信 POST /repos/{owner}/{repo}/hooks/{hook_id}/deliveries/{delivery_id}/attempts REST API
配信の ID X-GitHub-Delivery(GUID)。再配信でも同じ値 推奨
本文の上限 25MB。超えるイベントは配信されない イベントと本文
送信元 IP https://api.github.com/meta の hooks。IP での許可は勧めない GitHub の IP

届くヘッダー

ヘッダー 中身
X-GitHub-Hook-ID Webhook の ID
X-GitHub-Event 配信を起こしたイベントの名前
X-GitHub-Delivery 配信を見分ける GUID
X-Hub-Signature-256 HMAC-SHA256 の署名(secret を設定したとき)
X-Hub-Signature HMAC-SHA1 の署名(secret を設定したとき)
User-Agent 常に GitHub-Hookshot/ で始まる
X-GitHub-Hook-Installation-Target-Type Webhook を作ったリソースの種類
X-GitHub-Hook-Installation-Target-ID Webhook を作ったリソースの ID

GitHub は、処理の前に X-GitHub-Event のイベントの種類と、本文の最上位の action を確かめるよう勧めています。

署名の検証

X-Hub-Signature-256 は sha256= の後ろに、secret を鍵にした本文の HMAC-SHA256 を hex で並べた値です。比べるときは定数時間の比較を使います。

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 は確かめ用の値を公開しています。secret が It's a Secret to Everybody、本文が Hello, World! のとき、署名は sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17 です。本文は JSON に変換する前のものを使います。フレームワークごとの取り方は生の本文の取り方の記事で扱いました。

10 秒以内に返す受け口

GitHub の推奨は、配信を受けてから 10 秒以内に 2XX を返すことです。受け口では、署名の検証、X-GitHub-Delivery での重複の除去、キューへの投入だけを行い、CI の起動や外部の API の呼び出しはワーカーで行います。

X-GitHub-Delivery は再配信でも同じ値なので、重複の除去のキーに使えます。GitHub はこのヘッダーを再生攻撃の防止にも使うよう書いています。

失敗した配信の定期的な再配信

自動の再送がないので、受け口が止まっていた間の配信は自分で再配信します。GitHub のドキュメントには、リポジトリの Webhook の失敗した配信を定期的に再配信するスクリプトの例があります(自動の再配信)。要点は次のとおりです。

  1. GitHub Actions のワークフローを 6 時間ごと(cron 20 */6 * * *)と手動で動かす。
  2. 前回の実行時刻をリポジトリの変数に保存する。初回は実行の 24 時間前から見る。
  3. GET /repos/{owner}/{repo}/hooks/{hook_id}/deliveries で配信の一覧を 100 件ずつ取る。
  4. 配信を guid でまとめ、同じ guid の中に status が "OK" のものが 1 つもなければ失敗とみなす。
  5. 失敗した guid ごとに 1 件だけ POST …/deliveries/{delivery_id}/attempts で再配信する。

トークンは、組み込みの GITHUB_TOKEN では権限が足りません。fine-grained の個人のアクセストークンなら、対象のリポジトリへのアクセスと、Webhook と変数の書き込みの権限が要ります。

同じ考え方を fetch で書くと次のようになります(ページ送りは省いています)。

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 });
}

再配信できるのは過去 3 日の配信なので、スクリプトの間隔は 3 日より十分短くします。6 時間ごとなら、スクリプト自体が何回か失敗しても間に合います。

送信元 IP で絞る場合

GitHub の Webhook の送信元の IP の範囲は、https://api.github.com/meta の応答の hooks に入っています。ただし、GitHub は次のように書いています(GitHub の IP、2026-09-27 に確認)。

  • IP アドレスは時々変わる。
  • IP での許可は勧めない。使う場合は API を定期的に確かめることを強く勧める。
  • meta API の一覧は網羅的なものではない。

また、meta API のリファレンスは、ドキュメントに載っている応答の値は例であり、常に API を直接取得するよう書いています(meta API)。IP で絞る場合も署名の検証は外さず、一覧を定期的に取得してファイアウォールの設定を更新する仕組みを用意します。IP での絞り込み全般は送信元 IP で受信を絞る記事で扱います。

secret の切り替え

GitHub の Webhook は、1 つの secret で署名します。Stripe のように新旧 2 つの署名を並べる期間はないので、切り替えは受け側で吸収します。

  1. 受け側を、新旧 2 つの secret のどちらかで合えば通すように変える。
  2. GitHub の Webhook の設定で secret を新しい値に変える。
  3. 新しい secret で届くことを確かめてから、受け側から古い secret を外す。

REST API で Webhook の設定を更新するときは、secret を渡し直す必要があります。GitHub のリファレンスは「以前に secret を設定していた場合、同じ secret か新しい secret を渡さないと secret は削除される」と書いています。受け側の切り替えの手順は鍵の切り替えの記事で詳しく扱います。

自社が送る側になるとき

GitHub の形は、再送を送る側で持たず、受ける側に任せる設計です。自社の顧客に Webhook を送る側では、受ける側が再配信のスクリプトを書かなくて済むよう、送る側で自動の再送を持つほうが親切です。再送の間隔と期間の決め方は再送の設計の記事で扱いました。

Webhook Admin は、送る側の自動の再送を持っています。既定では、すぐ・5 秒・5 分・30 分・2 時間・5 時間・10 時間・10 時間の 8 回(約 28 時間)で、送信先ごとに回数と間隔を選べます。再送でも webhook-id は同じ値です。配信の記録から手で送り直すこともでき、署名の鍵を切り替えた後の 24 時間は新旧 2 つの署名を付けるので、受け側は止まらずに鍵を替えられます。

自社のサービスから自動の再送付きで Webhook を送りたい場合は、Webhook Admin を無料で試せます(月 5 万通まで)。https://app.webhookadmin.com/signup

よくある質問

GitHub の Webhook は失敗しても再送されないのですか。

自動では再送されません。GitHub のドキュメントは、失敗した配信は手動か、コードを書いて扱うよう書いています。管理画面の Recent Deliveries から再配信するか、REST API で配信の一覧を取って失敗したものを再配信します。どちらも過去 3 日の配信が対象です。

送信元 IP の一覧はどこにありますか。

https://api.github.com/meta の応答の hooks に入っています。GitHub は IP アドレスは時々変わるとし、IP での許可は勧めていません。使う場合は API を定期的に取得して一覧を更新します。

secret を変えるときはどうすればよいですか。

Webhook の設定で secret を新しい値に変えます。GitHub の Webhook は 1 つの secret で署名するので、受け側は切り替えの間、新旧 2 つの secret のどちらかで合えば通すようにしておき、GitHub の側を変えた後に古い secret を外します。API で Webhook の設定を更新するときは、secret を渡さないと消えてしまう点に注意します。

関連記事