Problem Introduction
GitHub webhooks fail validation with X-Hub-Signature-256 header mismatch errors.
Why It Happens
- •Not stripping the "sha-256=" prefix before compare
- •Invalid payload byte encoding (UTF-8 required)
- •Legacy SHA-1 header being used
- •No secret configured in GitHub repo
Step-by-Step Fix
- 1Extract the X-Hub-Signature-256 header value.
- 2Strip the "sha-256=" prefix from the received signature.
- 3Compute HMAC-SHA256 of the raw payload bytes using your secret.
- 4Use a timing-safe equal comparison method.
- 5Ignore "ping" events gracefully.
Common Mistakes
- •Comparing "sha256=abcdef..." against "abcdef..."
- •Not setting a strong secret in Repo Settings
- •Failing on initial ping event
Debugging Workflow
Extract header -> hash payload -> secure compare -> process action.
Preventive Best Practices
- •Use Hookmetry to pinpoint if the mismatch is due to prefix padding or body encoding
Works with webhooks and other async event systems (including AI callbacks).
Instead of guessing, inspecting the exact payload and headers can help debug faster. Tools like Hookmetry support this workflow.
Try the free webhook testerRelated Documentation