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

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

公開日: 2026-11-17
Source: https://webhookadmin.com/blog/github-webhooks-guide/

## 要点

- 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 を設定したときだけ付く | [検証](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries) |
| 旧来の署名 | `X-Hub-Signature`（SHA-1）。互換のためだけに残されている | 同上 |
| 署名の対象 | 本文。UTF-8 として扱う | 同上 |
| 応答の期限 | 10 秒以内に 2XX を返す。10 秒を超えると失敗として記録 | [推奨](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks)、[失敗の扱い](https://docs.github.com/en/webhooks/using-webhooks/handling-failed-webhook-deliveries) |
| 自動の再送 | なし | [失敗の扱い](https://docs.github.com/en/webhooks/using-webhooks/handling-failed-webhook-deliveries) |
| 手動の再配信 | 過去 3 日の配信。リポジトリの Webhook は管理者、組織の Webhook は組織の owner | [再配信](https://docs.github.com/en/webhooks/testing-and-troubleshooting-webhooks/redelivering-webhooks) |
| API での再配信 | `POST /repos/{owner}/{repo}/hooks/{hook_id}/deliveries/{delivery_id}/attempts` | [REST API](https://docs.github.com/en/rest/repos/webhooks) |
| 配信の ID | `X-GitHub-Delivery`（GUID）。再配信でも同じ値 | [推奨](https://docs.github.com/en/webhooks/using-webhooks/best-practices-for-using-webhooks) |
| 本文の上限 | 25MB。超えるイベントは配信されない | [イベントと本文](https://docs.github.com/en/webhooks/webhook-events-and-payloads) |
| 送信元 IP | `https://api.github.com/meta` の `hooks`。IP での許可は勧めない | [GitHub の IP](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses) |

## 届くヘッダー

| ヘッダー | 中身 |
|---|---|
| `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 で並べた値です。比べるときは定数時間の比較を使います。

```ts
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 に変換する前のものを使います。フレームワークごとの取り方は[生の本文の取り方の記事](https://webhookadmin.com/blog/webhook-raw-body-by-framework/)で扱いました。

## 10 秒以内に返す受け口

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

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

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

自動の再送がないので、受け口が止まっていた間の配信は自分で再配信します。GitHub のドキュメントには、リポジトリの Webhook の失敗した配信を定期的に再配信するスクリプトの例があります（[自動の再配信](https://docs.github.com/en/webhooks/using-webhooks/automatically-redelivering-failed-deliveries-for-a-repository-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 で書くと次のようになります（ページ送りは省いています）。

```ts
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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses)、2026-09-27 に確認）。

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

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

## 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 は削除される」と書いています。受け側の切り替えの手順は[鍵の切り替えの記事](https://webhookadmin.com/blog/webhook-secret-rotation/)で詳しく扱います。

## 自社が送る側になるとき

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

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

自社のサービスから自動の再送付きで Webhook を送りたい場合は、Webhook Admin を無料で試せます（月 5 万通まで）。[https://app.webhookadmin.com/signup](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 を渡さないと消えてしまう点に注意します。
