GitHub webhooks

GitHub webhooks

A webhook endpoint is three things that get confused with each other: a verifier, a router, and a set of handlers. Most broken integrations are broken because those three were written as one function — the verifier trusts a parsed body, the router is an if chain nobody can enumerate, and a handler's slow work happens inside the ten seconds GitHub allows before it calls the delivery failed.

This skill separates them, and carries a reference for what each event type actually contains so a handler is written against real fields rather than remembered ones.

It composes with two companions in the same pack: release-ledger orchestrates a since-you-were-away ledger and consumes captured merge events, and describe-changes turns one of those changes into prose. Install either with npx skills add crissmoldovan/agent-skills.

When to Use

• An application needs to react to activity on a GitHub repository or organization, and no endpoint exists yet.
• An endpoint exists and you are adding an event type, or auditing whether its verification is real.
• Deliveries are arriving and being lost, timing out, or processed twice.
• You need to know which event carries a field before designing a feature around it — that is what the event reference is for.

Do not use it for outbound calls to the GitHub API; that is the REST or GraphQL API and needs a credential this endpoint deliberately does not hold. Do not use it for GitHub Actions workflow triggers — on: pull_request in a workflow file is a different mechanism with a different payload shape and no endpoint of yours. Do not use it to poll: if you find yourself scheduling a fetch of recent merges, you are building a poller, and a poller has different idempotency and rate-limit concerns than anything here.

Prerequisites

1. A publicly reachable HTTPS URL that GitHub can POST to, or a tunnel to a local port for development. Complete when: an unauthenticated POST from outside your network reaches your handler.
2. A shared verification value, stored as a secret. Generate a long random value; place it with your platform's secret mechanism, never in the repository. Complete when: the running process reads it from the environment and the value has never appeared in a file, a log line, or a chat message.
3. Access to the raw request body. HMAC is computed over the exact bytes GitHub sent. A framework that hands you a parsed object has already destroyed the thing you need to verify. Complete when: you can log the byte length of the body and it matches the Content-Length header.
4. Somewhere to put work that is not the request. A queue, a job runner, or at minimum a durable table the response does not wait on. Complete when: you can enqueue and return in the same request, and see the work complete afterwards.
5. Admin rights on the repository, organization, or App whose settings hold the hook. Complete when: you can open the webhook settings page and see the Recent Deliveries tab.

Procedure

1. Audit what already exists. Search for a route matching webhook, hooks, or github and read it end to end before adding anything. Answer four questions: does it verify, does it verify against the raw body, which events does it already subscribe to, and does it filter events before doing work? The fourth matters most when you are adding a consumer: a handler that returns early for events it does not care about will discard yours too if you nest inside it.
2. Design the event map before writing code. A table of event, actions you care about, the predicate that selects them, and the handler. Keep it in the repository — it is the document that answers "why are we subscribed to that?" in a year. The event reference is the raw material; the payload cookbook has the predicates for the common cases already written.
3. Implement the endpoint in four layers, in this order.
   • Read the raw body as bytes.
   • Verify X-Hub-Signature-256 with HMAC-SHA256 and a constant-time compare. Reject with 401 on mismatch, and reject when the header is absent — an endpoint that skips verification when the header is missing is unverified.
   • Route on X-GitHub-Event and, where the event has one, payload.action.
   • Hand off to a handler that enqueues and returns. Respond 2xx within a second or two; GitHub's delivery timeout is ten seconds and a timed-out delivery is retried, which is how one merge becomes three ledger rows.
4. Handle the ping event explicitly. GitHub sends it when the hook is created. Returning 200 with no special case is fine, but returning 400 for an unknown event means the hook shows a red delivery from the moment it exists.
5. Register the hook. Create it against the repository or organization, select only the events in the map, set the content type to application/json, and set the verification value. Selecting "send me everything" is how an endpoint ends up receiving thousands of deliveries it discards.
6. Verify with a real delivery. Cause the event, then open Recent Deliveries and read the request and response. A 200 you produced by hand-posting a fixture proves your parser works and proves nothing about the hook.
7. Write the event map into the host repository's docs with the endpoint URL path, the events subscribed, and how to rotate the verification value.

Managing evolution

• Adding an event is three steps in one change: extend the map, add the handler, then update the hook's subscription list. Doing the third first means live deliveries hitting a router that does not know them.
• Idempotency comes from a natural key, not from the delivery id. GitHub's X-GitHub-Delivery is unique per attempt group and a manual redelivery reuses it — but a second, genuinely separate delivery of the same underlying fact (a synchronize after a synchronize) has a new one. Deduplicate on what the fact is: repository plus pull request number, or the head SHA plus check name. Keep the delivery id in the log line, not in the unique constraint.
• Replay is the debugging tool. Recent Deliveries has a Redeliver button, and the API exposes the same thing, so a fixed handler can be tested against the exact bytes that broke it.
• Local development uses forwarding, not a fixture. gh webhook forward (from the cli/gh-webhook extension) relays live deliveries to a local port with real signatures, which exercises the verifier that a saved JSON file never will.

Usage Examples

Set up GitHub webhook handling in this app. Audit anything that exists first,
then implement the endpoint: raw body, HMAC-SHA256 verification with a
constant-time compare, routing on the event header plus action, and a handler
that enqueues. Only subscribe to pull_request and push for now.

We already receive pull_request events but the handler returns early unless the
title matches our ticket convention. I need every merged PR. Show me how many
deliveries that filter discards, then add a second consumer beside it rather
than inside it.

Add check_run to our event map. Route only completed check runs whose conclusion
is failure or timed_out, on the default branch, and tell me which payload fields
the predicate reads.

Pitfalls

• Verifying a re-serialized body. JSON.stringify(await req.json()) is not the bytes GitHub signed. Key order, whitespace, and unicode escaping all differ, and the signature will never match — or worse, will match in development and fail in production behind a proxy that reformats.
• Comparing signatures with ===. Use a constant-time comparison. Compare fixed-length buffers, and check the length before comparing, because most constant-time helpers throw on a length mismatch rather than returning false.
• Trusting X-Hub-Signature. The unsuffixed header is the legacy SHA-1 signature. Verify the -256 one; accepting either lets a caller choose the weaker algorithm.
• Doing the work inline. Anything that calls a model, another API, or a slow query belongs behind a queue. A ten-second timeout means a slow handler turns into retries, and retries turn into duplicates.
• Returning a non-2xx for events you do not handle. GitHub retries failures. An unrouted event should return 200 and be counted, not rejected.
• Assuming every event has an action. push, status, create, delete, fork, gollum, and public have none. A router that reads payload.action unconditionally routes them all to the same undefined branch.
• Assuming a merge. pull_request with action: "closed" fires for closed and for merged. payload.pull_request.merged is the field that distinguishes them, and it is a boolean on the pull request, not on the event.
• Assuming the push commit list is complete. Large pushes truncate the commits array; the payload is a notification, not an archive. Read the range with the API if you need every commit.
• A payload that is a delete. push with after equal to all zeros is a branch deletion arriving as a push. Handlers that diff before..after produce nonsense on it.
• Subscribing to everything "to be safe". Every unwanted event is delivery volume, log noise, and a payload you did not review for the data it carries.
• Placing the endpoint behind the app's authentication. It has no session and no bearer token; its authentication is the signature. Exempt the route deliberately and narrowly, and make sure the exemption does not extend to the routes you add next.

Verification

• The endpoint reads the raw request body and verifies HMAC-SHA256 over those exact bytes.
• Comparison is constant-time, and a missing signature header is rejected rather than skipped.
• A deliberately corrupted signature was sent and produced 401.
• The router handles events without an action field.
• ping returns 200.
• Unrouted events return 200 and are counted.
• Handlers enqueue; nothing slow runs inside the request.
• Median response time to GitHub is well under the ten-second delivery timeout.
• Deduplication uses a natural key, and a redelivery was replayed to prove it.
• The hook subscribes only to the events in the map.
• A real delivery was inspected in Recent Deliveries, request and response.
• The verification value lives in a secret store and appears in no file, log, or message.
• The event map is documented in the host repository, with the rotation procedure.

Deeper reading

• Event types: every event this skill routes, its actions, the payload fields that carry the meaning, and one line on when you would subscribe to it.
• Payload cookbook: worked predicates — merged-PR-to-default-branch, tag push, check regression, review approval, successful deployment — each written as a condition plus the exact fields it reads.