GitHub Webhook Setup

Most CI/CD and automation pipelines lean on GitHub webhooks. Setting one up takes a few minutes. The main decision upfront is whether you want events from a single repository or your whole organisation.

Before you start

You'll need:

• A Webhook Watchtower account with a workspace
• Admin access to the GitHub repository or organisation

Step 1: Create a source in Watchtower

1. Go to Sources in your project.
2. Click Add source and choose GitHub as the provider.
3. Give it a name ("GitHub" is pre-filled, but "GitHub (org)" or "GitHub (my-repo)" works better if you have multiple).
4. Leave the signing secret blank for now; you'll generate one in the next step.
5. Click Create source and copy the generated ingest URL.

Step 2: Add the webhook in GitHub

For a repository: Go to the repository → Settings → Webhooks → Add webhook.

For an organisation: Go to your organisation → Settings → Webhooks → Add webhook.

Fill in the form:

• Payload URL: paste your Watchtower ingest URL
• Content type: set to application/json
• Secret: leave blank for now. You'll generate one in the next step.
• Which events: choose individual events or Send me everything

Click Add webhook. GitHub saves the webhook and immediately sends a ping event.

Step 3: Set a webhook secret

GitHub doesn't generate a secret for you. You create one. Use any long random string (a UUID works well, or run openssl rand -hex 32 in your terminal).

1. In GitHub, edit the webhook you just created and paste your secret into the Secret field. Save.
2. In your Watchtower source settings, paste the same secret and save.

The ping event GitHub sent in step 2 won't have a signature (it was sent before you set the secret), so it'll show as Skipped in your dashboard. All subsequent events will be Verified.

Step 4: Verify delivery

GitHub shows every delivery attempt in the webhook's Recent Deliveries tab. The ping event should show a 200 response. If it shows a non-2xx, check that the ingest URL is correct.

Trigger a real event (open a pull request, push a commit, etc.) and confirm it appears in your dashboard with a Verified stamp.

Duplicate event detection

GitHub adds an X-GitHub-Delivery header to every webhook request: a UUID unique to that delivery attempt. Watchtower stores this ID and uses it to detect when GitHub re-delivers the same event.

If a duplicate arrives:

• It's stored with a Duplicate label and a link to the original event
• It's not forwarded to your destinations
• It doesn't count toward your monthly event usage

GitHub does not automatically retry failed deliveries. Manual redelivery or your own recovery script can resend an event; Watchtower suppresses recognized ingest duplicates, but deliberate manual replay still requires idempotency at your endpoint.

What GitHub's signature looks like

GitHub puts the signature in the X-Hub-Signature-256 header:

sha256=abc123...

It's a standard HMAC-SHA256 over the raw request body, hex-encoded. Watchtower strips the sha256= prefix and verifies the digest against your configured secret.

Organisation vs repository webhooks

Organisation webhooks receive events across all repositories in the organisation. Repository webhooks only receive events from that one repository. Use an organisation webhook if you want a single source covering all repos; use repository webhooks if you need per-repo event logs.

Common issues

Skipped verification on first ping: normal. GitHub sends the ping before you've set a secret, so there's no signature to verify.

Failed verification after setting the secret: re-copy the secret from GitHub's webhook settings and paste it fresh into your Watchtower source. A trailing newline in the secret is a common cause of mismatches.

Events not appearing: check Recent Deliveries in GitHub. GitHub shows the full response but does not automatically retry failures. Use manual redelivery or your own recovery script. A 200 from the ingest URL means it arrived. Check your Watchtower event log for the delivery status to your destination.