Why would you use a GitHub webhook instead of polling the GitHub REST API for changes?

## What a GitHub webhook is A webhook is a subscription: you give GitHub a payload URL and tell it which events you care about, and GitHub makes an HTTP POST to that URL whenever one of those events happens. Webhooks can be attached at several scopes — a single repository, an entire organization, a GitHub App (the app has one webhook and receives events from every account that installs it), or an enterprise. The configuration for each is the same handful of fields: the payload URL, the content type (`application/json` or `application/x-www-form-urlencoded`), an optional secret used to sign deliveries, SSL verification, and the event selection (just pushes, everything, or a specific list such as `pull_request`, `issues`, `check_run`). ## What a delivery looks like A delivery is an ordinary HTTP request from GitHub's servers. The headers that matter are: - `X-GitHub-Event` — the event name, for example `push` or `pull_request`. - `X-GitHub-Delivery` — a GUID unique to this delivery, which is what you use to detect duplicates. - `X-GitHub-Hook-ID` — the numeric ID of the webhook that produced it. - `X-Hub-Signature-256` — an HMAC signature over the body, present only when the webhook has a secret configured. - `User-Agent` — begins with `GitHub-Hookshot/`. The body is a JSON object. Most event payloads include an `action` field (`opened`, `closed`, `synchronize`, …), plus `repository` and `sender` objects, and for GitHub Apps an `installation` object identifying which installation the event came from. ## Why polling is the worse default **Latency.** With a one-minute poll you learn about a merge up to a minute late. A webhook arrives in roughly the time it takes GitHub to make one HTTP request. **Rate limit.** Authenticated REST requests draw on an hourly primary quota (5,000 requests per hour for a personal access token at the time of writing; unauthenticated requests get only 60 per hour per IP address). A poller spends that budget on every tick regardless of whether anything changed, and the cost multiplies by the number of repositories you watch. Conditional requests help — sending `If-None-Match` with a previously returned `ETag` and receiving `304 Not Modified` does not count against the primary rate limit — but you still pay in requests that return 200, and you still pay in latency. **State versus transitions.** The API shows you the current state of a resource. If a label was added and removed, or a review was requested and dismissed, between two polls, you will never see it. Webhook events describe the transition itself, which is what most automations actually key on. **Complexity.** A correct poller needs cursors, watermarks, and per-resource change detection. A webhook receiver needs an HTTP endpoint. ## When polling is still correct - Your receiver has no public inbound HTTP — behind a corporate firewall, on a laptop, or in a network where you cannot expose a port. - You need a backfill or reconciliation pass: webhook delivery is best-effort, so a periodic sweep that compares your database against the API catches anything that was dropped while you were down. - The thing you need has no corresponding event. The mature answer in an interview is "both": webhooks for freshness, a low-frequency reconciliation poll for correctness. ## What a receiver must do 1. **Verify the signature** before parsing anything, using the raw request bytes and the shared secret. An unverified endpoint is an open door for anyone who learns the URL. 2. **Respond quickly with a 2xx.** GitHub expects a response within about ten seconds; long processing inside the request handler turns into failed deliveries. 3. **Enqueue and process asynchronously.** Acknowledge, then do the work. 4. **Deduplicate on `X-GitHub-Delivery`.** Delivery is at-least-once in practice, and a delivery can be replayed manually, so handlers should be idempotent. 5. **Do not assume ordering.** Two events fired close together can arrive in either order; where order matters, re-read the current state from the API rather than reconstructing it from the event sequence. ## Common mistakes Treating the payload as trusted input, doing the whole job inline and timing out, assuming exactly-once delivery, and assuming a webhook removes the need for the API entirely — most handlers still call the API to fetch details the payload does not carry.