Blog

Common GitHub Webhook Mistakes

GitHub webhooks are easy 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

  • 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

  • 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.

Next