Skip to content
turbodog

POST /webhook/github

Summary

Receives and processes incoming GitHub webhook events.

Intent

This endpoint exists to accept webhook payloads sent by GitHub (e.g., push, pull request, installation events) and route them through the internal webhook handling pipeline, enabling the system to react to repository changes and GitHub App installation events in real time.

Parameters

No parameters.

Request example

Terminal window
curl -X POST https://maps.google.com//webhook/github \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  -H "X-Hub-Signature-256: sha256=<HMAC_SIGNATURE>" \
  -d '{
    "ref": "refs/heads/main",
    "repository": {
      "id": 123456789,
      "name": "my-repo",
      "full_name": "acme/my-repo"
    },
    "installation": {
      "id": 987654
    },
    "head_commit": {
      "id": "abc123def456"
    }
  }'

Response example

"Response shape not determinable from source code alone — verify against live API."

Error cases

  • 400 — The webhook payload is malformed or cannot be parsed
  • 401 — The HMAC signature (X-Hub-Signature-256) does not match the configured webhook secret
  • 500 — An internal error occurs while processing the webhook event or enqueuing the job

Gotchas

  • GitHub signs webhook payloads using HMAC-SHA256 with a shared secret. The handler reads the raw request body (not the parsed JSON) to verify this signature — any middleware that modifies or re-serializes the body before it reaches this handler will break signature validation.
  • The handler extracts the raw body via request.body.__rawBody first, falling back to re-serializing the parsed body. Ensure your Fastify setup preserves the raw buffer on the request body object if signature verification is required.
  • All GitHub webhook headers (e.g., X-GitHub-Event, X-Hub-Signature-256, X-GitHub-Delivery) must be forwarded exactly as sent by GitHub — do not strip or rename them.
  • The response status code is determined entirely by the internal handleWebhook result, not a fixed value. GitHub expects a 2xx response within a few seconds or it will retry the delivery.
  • GitHub will retry failed webhook deliveries (non-2xx or timeout). Ensure the endpoint is idempotent or that duplicate events are handled gracefully downstream.