GitHub webhooks
Last verified against GitHub's documentation on September 27, 2026.
GitHub sends webhooks when something happens in a repository, organization, or GitHub App installation: a push, a pull request, a workflow run, a security alert. Most delivery problems come from a few causes: a handler that takes longer than 10 seconds, a signature check running against the wrong secret or a modified body, or a server that was down when GitHub tried to deliver. GitHub doesn’t retry failed deliveries, so every one of those failures is a lost event unless someone redelivers it. This page covers what GitHub sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What GitHub sends webhooks for
GitHub has dozens of event types, and many have several actions, such as opened, closed, or completed, carried in the payload’s top-level action field. These are the ones most integrations use.
| Area | Key events | Typical use |
|---|---|---|
| Code | push, create, delete | Trigger builds and deploys, track branches and tags |
| Pull requests | pull_request, pull_request_review, pull_request_review_comment | Run checks, post bot comments, enforce review rules |
| Issues | issues, issue_comment | Sync issues with a tracker, run triage bots |
| CI and checks | workflow_run, workflow_job, check_run, check_suite, status | Report build results, trigger downstream pipelines |
| Deployments and releases | deployment, deployment_status, release | Drive deploy systems, announce releases |
| Security | dependabot_alert, code_scanning_alert, secret_scanning_alert | Route alerts to the team that owns them |
| GitHub Apps | installation, installation_repositories | Track which accounts and repositories installed your app |
| Setup | ping | Sent when a webhook is created, to confirm the URL works |
Webhooks can live on a repository, an organization, a GitHub App, a GitHub Marketplace listing, or a GitHub Sponsors account. Not every event is available to every type: an organization webhook can subscribe to team, but a repository webhook can’t.
Subscribe only to the events you handle. GitHub recommends this both to reduce load on your server and to avoid throttling.
How GitHub delivers webhooks
| Behavior | Detail |
|---|---|
| Signature header | X-Hub-Signature-256, formatted sha256=<hex>: an HMAC-SHA256 of the raw request body, keyed with your webhook secret. Only sent if you set a secret |
| Legacy signature | X-Hub-Signature (HMAC-SHA1), kept only for older integrations |
| Timestamp | None. GitHub’s signature doesn’t expire |
| Other headers | X-GitHub-Event (event name), X-GitHub-Delivery (unique ID, unchanged on redelivery), X-GitHub-Hook-ID, and a GitHub-Hookshot/ user agent |
| Content type | application/json, or application/x-www-form-urlencoded with the JSON in a payload field |
| Timeout | 10 seconds for a 2xx response |
| Automatic retries | None |
| Manual redelivery | Deliveries from the past 3 days, from the UI or the REST API |
| Payload cap | 25 MB. Larger payloads aren’t delivered at all |
| Ordering | Not guaranteed. Use timestamps inside the payload |
| Throttling | GitHub may slow deliveries during a surge |
| Webhook limit | 20 repository or organization webhooks per event type |
| URL | Must be reachable from the internet. localhost and 127.0.0.1 are rejected |
| Source IPs | Published through the GET /meta API (IPv4 and IPv6), and they change occasionally |
Common GitHub webhook errors and how to fix them
“Timed out”
GitHub didn’t get a response within 10 seconds, so it closed the connection and recorded the delivery as failed. It won’t try again on its own. Respond with 2xx as soon as the request is verified, then do the real work from a queue. Handlers that call the GitHub API, run a build, or post a comment before responding are the usual cause.
“Invalid HTTP response”
Your server returned a 4xx or 5xx status. GitHub records any non-2xx response as a failure. Check your application logs for the matching request. Common causes are a failed signature check returning 401, authentication middleware blocking the route, or a crash in the handler.
Signature verification fails
If you’re sure the delivery came from GitHub but the check fails:
- No secret is set. GitHub only sends
X-Hub-Signature-256when the webhook has a secret configured. - Wrong header or algorithm.
X-Hub-Signature-256uses HMAC-SHA256.X-Hub-Signatureuses SHA-1 and exists only for legacy integrations. - Wrong secret. Each webhook has its own secret. If you don’t know the current value, set a new one in the webhook settings and update your server.
- The body changed before verification. A JSON parser, proxy, or load balancer that re-serializes the body breaks the signature. Verify against the raw bytes. With the form-encoded content type, verify the whole raw body, not the decoded
payloadfield. - Encoding. Payloads can contain Unicode. If your framework applies a character encoding, handle the body as UTF-8.
“Failed to connect to host” or “Failed to connect to network”
GitHub couldn’t resolve your hostname, or your server refused the connection. Check DNS with nslookup, and make sure your firewall allows GitHub’s current webhook IPs from the GET /meta API.
“Peer certificate cannot be authenticated with given CA certificates”
Your TLS setup is broken, usually because of a self-signed certificate or a server that doesn’t send its full certificate chain. Test with an SSL server test or openssl s_client -connect host:443.
“URL host localhost is not supported”
GitHub won’t deliver to localhost or 127.0.0.1. You need a public URL that forwards to your machine.
“Cannot have more than 20 webhooks”
Each repository or organization allows 20 webhooks per event type. GitHub’s own documentation suggests running a proxy that receives each delivery once and forwards it to as many destinations as you need.
Deliveries that never arrive
If a delivery doesn’t appear in the webhook’s Recent Deliveries log, GitHub never attempted it. Check that the event happened where the webhook is configured, that the webhook subscribes to that event and is active, and that OAuth app access restrictions haven’t disabled it. Some events have documented limits: create and delete don’t fire when more than three tags are pushed at once, and payloads over 25 MB are never sent. Deliveries can also take a few minutes to show up.
Deliveries out of order or delayed
GitHub doesn’t guarantee order, and it may throttle deliveries during a surge. When order matters, compare timestamps inside the payload, or fetch the current state from the API instead of trusting arrival order.
Why use HookDeploy with GitHub
No more lost deliveries
GitHub doesn’t retry. If your server is down, slow, or mid-deploy when a delivery arrives, that event is recorded as failed and stays that way until someone redelivers it by hand, within 3 days.
HookDeploy captures each delivery at Cloudflare’s edge and responds to GitHub well inside the 10-second limit, before forwarding it to your server. From there:
- Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
- Incidents. Forward failures are grouped into incidents, and you can bulk-replay them at a controlled rate once your server recovers.
- Longer history. GitHub keeps 3 days of deliveries. HookDeploy keeps them for your plan’s retention period, from 7 days on Free to 365 days on Enterprise, and any of them can be replayed.
Signature verification works on every retry and replay
On first delivery, HookDeploy forwards GitHub’s original body and X-Hub-Signature-256 header unchanged. That header is on HookDeploy’s protected list: it’s never redacted from stored requests, and custom header strip rules can’t remove it.
GitHub’s signature has no timestamp, so unlike providers such as Stripe, a delivery retried an hour later or replayed a week later still verifies. Two things do break it:
- Transformations. A transformation changes the body, so the signature won’t match at that destination. Use transformations for destinations that don’t verify GitHub’s signature, and protect those with an injected auth header.
- Privacy filters. Retries and replays send the stored copy of the request. If a privacy filter or body key sanitization changed what was stored, the signature won’t match.
Fan out past the 20-webhook limit
One GitHub webhook pointed at HookDeploy can forward every delivery to your CI system, a deploy service, a Slack channel, and an internal dashboard in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Deliver to systems GitHub can’t reach
GitHub needs a public URL, but self-hosted CI servers, deploy tools, and internal services usually sit behind a firewall. The HookDeploy Agent connects outward from your network over mTLS and delivers to a local port, so GitHub webhooks reach private systems with no public IP, open port, or exposed route.
Develop against live GitHub traffic
GitHub won’t deliver to localhost. A tap sends a temporary copy of live deliveries to 127.0.0.1 on your machine while production keeps receiving them. You can also replay any captured delivery to your local handler, which is faster than opening a pull request every time you want a new pull_request event.
Know the limits
- Payload size. GitHub payloads can be up to 25 MB. HookDeploy accepts payloads up to 256 KB on Free, 1 MB on Starter, 25 MB on Pro and Scale, and 100 MB on Enterprise, so Pro and above cover GitHub’s maximum. A larger payload gets a
413, and since GitHub doesn’t retry, that delivery is lost. If you handle largepushorcreateevents on Free or Starter, watch for413responses in the webhook’s Recent Deliveries log. - IP allowlisting. HookDeploy’s quick-add covers GitHub’s IPv4 webhook ranges, but GitHub also publishes IPv6 ranges, and the allowlist supports IPv4 only. A delivery arriving over IPv6 would be rejected while the allowlist is on. For GitHub, rely on signature verification in your handler.
- Tokens in the URL. GitHub can’t send custom headers, so HookDeploy’s secret token would have to go in the webhook URL, and GitHub advises against putting credentials in payload URLs. Use the webhook secret and signature verification instead.
Retries, replays, and duplicates
Because GitHub’s signature doesn’t expire, retries and replays from HookDeploy verify exactly like the original delivery. The part to get right is duplicates.
HookDeploy forwards GitHub’s original headers, including X-GitHub-Delivery. That ID stays the same when GitHub redelivers, and it stays the same when HookDeploy retries or replays. Record each delivery ID you’ve processed and skip any you’ve already handled. That protects you from replay attacks and from double-processing when a retry lands after your handler already succeeded.
To reprocess an event on purpose, for example after fixing a bug in your handler, clear that delivery ID from your processed list before replaying it.
Set up GitHub with HookDeploy
- In HookDeploy, create an endpoint (for example,
GitHub production) and copy its URL. - On GitHub, open the repository or organization, go to Settings, then Webhooks, and click Add webhook. For a GitHub App, set the webhook URL in the app’s settings instead.
- Paste your HookDeploy URL as the Payload URL and set Content type to
application/json. - Enter a random, high-entropy Secret and store the same value on your server. Leave SSL verification enabled.
- Choose Let me select individual events and pick only the events you handle. Make sure Active is checked, then click Add webhook. GitHub immediately sends a
pingevent, which should appear in HookDeploy. - In HookDeploy, add a forward destination pointing to your handler, or to an agent for private delivery, and set its retries.
Example handler (Node.js and Express)
import crypto from 'node:crypto';
import express from 'express';
const app = express();
// Raw body parser on this route, registered before any global JSON middleware.
app.post('/webhooks/github', express.raw({ type: 'application/json' }), async (req, res) => {
const signature = req.get('x-hub-signature-256') ?? '';
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.GITHUB_WEBHOOK_SECRET)
.update(req.body) // raw bytes, untouched
.digest('hex');
const valid =
signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
if (!valid) return res.status(401).send('Invalid signature');
res.sendStatus(202); // respond well inside GitHub's 10 seconds
await enqueue({
deliveryId: req.get('x-github-delivery'), // skip IDs you've already handled
event: req.get('x-github-event'),
payload: JSON.parse(req.body.toString('utf8')),
});
});
FAQ
Does HookDeploy break GitHub signature verification?
No. HookDeploy forwards GitHub's original body and X-Hub-Signature-256 header unchanged. GitHub's signature has no timestamp, so retries and replays verify too, no matter how late they arrive. Verification fails only when a transformation changes the body, or when a privacy filter changed the stored copy used for retries and replays.
What happens to GitHub webhooks when my server is down?
GitHub doesn't retry failed deliveries, so without something in front of your server, those events are gone unless you redeliver them by hand within 3 days. HookDeploy captures every delivery and responds to GitHub right away, then retries forwarding on your destination's schedule. You can replay anything that still failed once your server is back.
Can I receive GitHub webhooks on localhost?
GitHub rejects localhost and 127.0.0.1 as webhook URLs. Point the webhook at HookDeploy, then start a tap from the Desktop Agent or CLI to copy live deliveries to a local port, or replay a captured delivery to your local handler.
How long can I replay GitHub deliveries?
GitHub lets you redeliver from the past 3 days. HookDeploy keeps captured deliveries for your plan's retention period, 7 days on Free, 30 on Starter, 90 on Pro, 180 on Scale, and 365 on Enterprise, and you can replay any of them.
Should I use HookDeploy's IP allowlist for GitHub?
Rely on signature verification instead. GitHub publishes IPv6 ranges for webhook deliveries, and HookDeploy's IP allowlist supports IPv4 only, so a GitHub delivery that arrives over IPv6 would be rejected while the allowlist is on.
Does HookDeploy work with GitHub Apps?
Yes. Set your GitHub App's webhook URL to a HookDeploy endpoint and every event the app receives, including installation events, is captured and forwarded like any other delivery.