DEV Community

Cover image for GitHub Webhooks: Signatures, 10-Second Timeout, Redelivery, and IP Ranges
mmiura for SHANNON LIMITED LIABILITY COMPANY

Posted on Originally published at webhookadmin.com

GitHub Webhooks: Signatures, 10-Second Timeout, Redelivery, and IP Ranges

GitHub doesn't retry failed webhook deliveries, which surprises a lot of people the first time an endpoint goes down. We checked GitHub's docs and put the signature, the 10-second timeout, redelivery and IP ranges in one place.

GitHub does not retry failed webhook deliveries. If your endpoint was down, you redeliver what you missed yourself, from the UI or the REST API, and only deliveries from the past 3 days are eligible. A delivery that takes more than 10 seconds to answer is recorded as a failure too. This post puts GitHub's webhook behavior in one table, checked against the official docs on 2026-09-27, then covers redelivering failures on a schedule and what to do about source IPs.

GitHub webhook behavior at a glance

Topic Behavior Source
Signature header X-Hub-Signature-256 (sha256= plus hex), sent only when a secret is configured Validating deliveries
Legacy signature X-Hub-Signature (SHA-1), kept for backward compatibility only Same
Signed content The payload; handle it as UTF-8 Same
Response deadline 2XX within 10 seconds; slower responses are recorded as failures Best practices, Failed deliveries
Automatic retries None Failed deliveries
Manual redelivery Deliveries from the past 3 days; repo admins for repository webhooks, org owners for organization webhooks Redelivering
API redelivery POST /repos/{owner}/{repo}/hooks/{hook_id}/deliveries/{delivery_id}/attempts REST API
Delivery ID X-GitHub-Delivery (a GUID); unchanged on redelivery Best practices
Payload cap 25 MB; larger events are not delivered Events and payloads
Source IPs hooks in https://api.github.com/meta; IP allowlisting not recommended GitHub's IP addresses

Headers on every delivery

Header Contents
X-GitHub-Hook-ID The webhook's ID
X-GitHub-Event The event that triggered the delivery
X-GitHub-Delivery A GUID identifying the delivery
X-Hub-Signature-256 HMAC-SHA256 signature (when a secret is set)
X-Hub-Signature HMAC-SHA1 signature (when a secret is set)
User-Agent Always starts with GitHub-Hookshot/
X-GitHub-Hook-Installation-Target-Type Type of resource the webhook was created on
X-GitHub-Hook-Installation-Target-ID ID of that resource

GitHub recommends checking both the X-GitHub-Event header and the payload's top-level action before processing.

Verifying the signature

X-Hub-Signature-256 is sha256= followed by the hex HMAC-SHA256 of the body, keyed with your secret. Compare in constant time.

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);
}
Enter fullscreen mode Exit fullscreen mode

GitHub publishes a test vector: with the secret It's a Secret to Everybody and the payload Hello, World!, the signature is sha256=757107ea0eb2509fc211221cce984b8a37570b6d7586c22c46f4379c8b043e17. Use the body before any JSON parsing; getting the raw request body shows how in eight frameworks.

Answering within 10 seconds

GitHub asks for a 2XX within 10 seconds. In the handler, verify the signature, drop duplicates by X-GitHub-Delivery, enqueue, and return. Kick off CI jobs or call other APIs from a worker.

Because X-GitHub-Delivery stays the same on redelivery, it works as your deduplication key. GitHub also points to it as the way to recognize replayed deliveries.

Redelivering failures on a schedule

With no automatic retries, whatever arrived while your endpoint was down is yours to redeliver. GitHub's docs include a script that does this for a repository webhook (automatic redelivery). It works like this:

  1. A GitHub Actions workflow runs every 6 hours (cron 20 */6 * * *) or on demand.
  2. It stores the last run time in a repository variable; on the first run it looks back 24 hours.
  3. It pages through GET /repos/{owner}/{repo}/hooks/{hook_id}/deliveries, 100 at a time.
  4. It groups deliveries by guid and treats a GUID as failed if none of its deliveries has status "OK".
  5. For each failed GUID it redelivers one delivery with POST …/deliveries/{delivery_id}/attempts.

The built-in GITHUB_TOKEN doesn't have enough permissions. A fine-grained personal access token needs access to the repository plus write permission for webhooks and variables.

The same idea with plain fetch (pagination left out):

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; // skip anything before the last run
  byGuid.set(d.guid, [...(byGuid.get(d.guid) ?? []), d]);
}
for (const [, group] of byGuid) {
  if (group.some((d) => d.status === 'OK')) continue; // already delivered once
  await fetch(`${base}/deliveries/${group[0]!.id}/attempts`, { method: 'POST', headers });
}
Enter fullscreen mode Exit fullscreen mode

Since only the past 3 days can be redelivered, run the job much more often than that. Every 6 hours leaves room for the job itself to fail a few times.

Allowlisting GitHub's IPs

GitHub's webhook source ranges are in the hooks field of https://api.github.com/meta. GitHub's docs (checked on 2026-09-27) say:

  • Its IP addresses change from time to time.
  • It doesn't recommend allowing by IP address, and if you do, it strongly encourages regular monitoring of the API.
  • The meta API list isn't intended to be exhaustive.

The meta API reference adds that the values shown in the docs are examples and you must always query the API for current values (meta API). If you filter by IP, keep verifying signatures and refresh your firewall rules from the API on a schedule. Webhook IP allowlisting covers the general approach.

Rotating the secret

A GitHub webhook signs with one secret at a time; there's no period where both old and new signatures are sent. Handle the overlap on your side:

  1. Make the receiver accept a signature from either the old or the new secret.
  2. Change the secret in the webhook settings.
  3. Once deliveries verify with the new secret, remove the old one from the receiver.

When you update a webhook through the REST API, include the secret. The reference says that if you previously had a secret set, you must provide the same secret or a new one, or the secret will be removed. Rotating signing secrets goes through the receiver side in more detail.

When you're the sender

GitHub's model leaves retries to the receiver. If you send webhooks to your own customers, retrying on your side saves them from writing redelivery scripts. We covered picking a schedule in designing webhook retries.

Webhook Admin retries automatically: by default immediately, then after 5 s, 5 min, 30 min, 2 h, 5 h, 10 h and 10 h (8 attempts, about 28 hours), and you can choose the number of retries and the interval per endpoint. Every attempt carries the same webhook-id. Deliveries can also be retried by hand from the log, and for 24 hours after a secret rotation each message carries both the old and the new signature. The free plan includes 50,000 messages a month: https://app.webhookadmin.com/signup

Quick FAQ

Does GitHub retry failed webhooks?

Not automatically. GitHub's docs say to handle failed deliveries manually or by writing code. Redeliver from Recent Deliveries in the webhook settings, or list deliveries through the REST API and redeliver the failures. Both work for deliveries from the past 3 days.

Where are GitHub's webhook IP addresses?

In the hooks field of https://api.github.com/meta. GitHub says its IP addresses change from time to time and does not recommend allowing by IP; if you do, poll the API regularly.

How do I change a GitHub webhook secret?

Update the secret in the webhook settings. GitHub signs with a single secret, so during the switch have your receiver accept either the old or the new secret, change it on GitHub, then drop the old one. When updating a webhook through the API, pass the secret again or it will be removed.


Thanks for reading! How do you pick up GitHub deliveries you missed: a redelivery script, a reconciliation job, or something else? We'd love to hear in the comments.

This post first appeared on the Webhook Admin blog.

Top comments (0)