Nirmion
HelpLog in Find a tool

Developer · THE NO-PANIC PLAN

Secure and test a GitHub webhook receiver

Build a GitHub-specific receiver that authenticates each raw delivery before acting, handles only the events you need, and recovers safely from duplicate or failed deliveries. This does not validate webhook signatures for other providers; each sender has its own signing contract.

MISSION implement and safely operate a GitHub webhook receiver

Start this workflow

THE REAL-WORLD BIT

What happens outside this browser tab?

Configure a minimal HTTPS endpoint and secret, verify GitHub?s HMAC signature over the original request body, validate event/action and authorization, enqueue work with delivery tracking, then test rejection, duplicate and failure paths.

YOUR CHECKLIST, WITH FEWER DRAMATIC SIGHES

One step at a time.

Follow the order below. If a step names a Nirmion tool, its link is right there with it.

  1. 01

    Configure a minimal, secret-protected endpoint

    Create a staging webhook endpoint over HTTPS and leave certificate verification enabled. Subscribe only to the event types you need. Set a high-entropy webhook secret and store it in your server?s approved secret manager or protected environment; never hardcode it, commit it, expose it in the payload URL, or paste it into a shared test tool. Restrict inbound access according to your deployment policy and keep the test endpoint separate from production.

  2. 02

    Authenticate the original request before parsing

    Read and preserve the exact raw request body bytes. Compute HMAC-SHA256 with the configured GitHub secret and compare the expected `sha256=` value with the `X-Hub-Signature-256` header using a constant-time comparison. Do not parse and reserialize the JSON before signature verification. Reject a missing or non-matching signature before parsing, queuing, logging payload contents or triggering any business action. Follow GitHub?s documented UTF-8 handling and use its official language example or a maintained library reviewed for this contract.

  3. 03

    Validate the GitHub event and authorize the requested action

    Only after signature verification, parse the JSON and inspect the `X-GitHub-Event` header plus any event-specific `action` field. Accept only expected event/action combinations and required fields; treat unknown fields and newly added actions defensively. Then apply your application?s own authorization and resource checks: a valid GitHub signature authenticates the sender and payload integrity but does not grant the payload permission to perform every requested business operation.

  4. 04

    Handle duplicate deliveries and respond promptly

    Use `X-GitHub-Delivery` as a delivery identifier and record processing state so a retry or replay cannot repeat a non-idempotent side effect. GitHub uses the same delivery ID when a delivery is redelivered, so allow a safely retried failed/unfinished attempt to resume while suppressing an already completed action. Acknowledge with a 2XX response within 10 seconds; place longer work on a durable queue before acknowledging. Monitor the webhook delivery history: GitHub does not automatically redeliver failed deliveries, so investigate and manually or programmatically redeliver when appropriate.

  5. 05

    Test the receiver?s security and recovery behavior

    In staging, use fake payload data and a staging-only test secret. Verify a valid test signature succeeds; missing, wrong and body-tampered signatures fail before side effects; unsupported event/action values are safely ignored or rejected; repeated delivery IDs do not duplicate completed work; failed and redelivered deliveries recover correctly; and slow handlers still durably queue work and return 2XX within the documented 10-second limit. Check that logs redact secrets and sensitive payload fields. Record the tested code/configuration version and unresolved failures. Nirmion?s similarly named Webhook Payload Tester was source-inspected: it only organizes entered rows and does not parse payload JSON or compute/verify GitHub HMAC signatures, so no Nirmion tool is linked as a validator.

RECEIPTS, PLEASE

Sources & review notes

Each source is linked to the steps it supports. Open it to check its scope and current guidance.

Source checked 2026-10-04