Blog
Common GitHub Webhook Mistakes
Common GitHub webhook mistakes are easy to make because webhooks are simple to turn on and surprisingly easy to wire incorrectly. The failures usually show up as duplicate CI runs, missing deployment triggers, signature mismatches, or pull request automation that fires on the wrong branch.
Most mistakes come from treating all GitHub events as the same shape.
Payload Mistakes
GitHub uses different payload contracts for push, pull_request, workflow_run, release, and other events. Route on the event name and action first, then read fields that are guaranteed for that specific event instead of relying on a shared-looking property.
- Treating push and pull_request payloads as interchangeable.
- Using head_commit.message without handling null head_commit cases.
- Routing by branch name without checking whether ref is a branch or tag.
- Assuming closed pull requests are always merged pull requests.
Operational Mistakes
Use the delivery ID, event name, action, repository, and branch together when tracing GitHub webhook failures. Verify the raw-body signature before routing, then replay only the affected destination after its handler is idempotent.
Keep provider redelivery distinct from an internal retry. GitHub redelivery creates a new inbound delivery, while retrying a stored FastHook event targets the existing failed branch and preserves the original request as evidence.
- Validating signatures against parsed JSON instead of the raw body.
- Ignoring X-GitHub-Delivery during debugging.
- Retrying failed deploy events without idempotency.
- Sending every event type to every destination.
- Using provider redelivery when an event retry would be safer.