Verify GitHub Webhook Signatures

[adarshm11]

Summary

The /webhook endpoint currently accepts any incoming POST request without verifying its origin. GitHub signs every webhook payload using a shared secret and includes the signature in the X-Hub-Signature-256 header. We should validate this header to reject forged or unauthorized requests.

Problem

Any party that knows the webhook URL can send arbitrary payloads to trigger deployments. This is a security risk — a bad actor could craft a push event payload and cause the server to run git pull and docker compose up on any configured repo.

Proposed Solution

1. Add a WEBHOOK_SECRET environment variable (set in .env).
2. In the /webhook handler, compute HMAC-SHA256 of the raw request body using the secret.
3. Compare against the X-Hub-Signature-256 header value using a constant-time comparison (hmac.compare_digest).
4. Return 403 Forbidden if the signature is missing or does not match.

import hmac, hashlib

def verify_signature(payload: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Acceptance Criteria

• WEBHOOK_SECRET is read from the environment on startup
• Requests with a missing or invalid X-Hub-Signature-256 header return 403
• Valid requests continue to be processed normally
• README is updated with instructions for setting the webhook secret in GitHub and .env

References

• GitHub docs: Validating webhook deliveries

[Ilia01]

Agreed with the direction here.

The one detail I would make explicit in the issue is that the HMAC must be computed from the untouched request body, not from an already-parsed JSON object or decoded string.

For GitHub webhooks the common failure pattern is:

• body parser runs first
• payload still looks fine in logs
• signature check fails because the bytes changed before verification

I would tighten the acceptance criteria to include:

• reject malformed X-Hub-Signature-256 headers, not just missing/invalid ones
• fail closed if WEBHOOK_SECRET is missing in environments where the endpoint is expected to be protected
• test a mutated-body case in addition to valid/invalid payloads

If you need to sanity-check the body/signature pair locally while implementing this, I built HookLens around that exact inspect/replay workflow: https://github.com/Ilia01/hooklens