GitHub Webhooks Integration Guide

This guide shows you how to use Charon Gate as a reliability layer for GitHub webhooks. Whether you're forwarding push events to a CI pipeline, repository events to an internal tool, or pull request events to a review bot, Charon Gate ensures every event is captured, verified, and delivered.

Prerequisites

• A Charon Gate account (sign up free)
• A GitHub repository or organisation where you can configure webhooks

1. Create a Charon Gate endpoint

1. Log in to the Charon Gate dashboard
2. Go to Endpoints → New endpoint
3. Select the GitHub template
4. Set Destination URL to your application's handler (e.g. https://your-app.com/webhooks/github)
5. Note the Ingest URL — you'll give this to GitHub

2. Configure a GitHub webhook

For a repository:

1. Go to your repository → Settings → Webhooks → Add webhook
2. Set Payload URL to your Charon Gate ingest URL
3. Set Content type to application/json
4. Set Secret — generate a strong random string (e.g. openssl rand -hex 32)
5. Choose which events to send (or Send me everything for full capture)
6. Click Add webhook

For an organisation:

Same steps, but go to your organisation → Settings → Webhooks.

3. Add the signing secret to Charon Gate

1. Open your endpoint in the Charon Gate dashboard → Settings
2. Paste the secret you generated into Ingest signing secret
3. Save

Charon Gate now verifies every X-Hub-Signature-256 header using HMAC-SHA256. Events that fail verification are rejected and logged — they never reach your application.

4. Test the webhook

GitHub provides a Recent Deliveries panel on each webhook. You can redeliver any event from there, or trigger a real event (e.g. push a commit) and watch it appear in the Charon Gate dashboard.

What Charon Gate handles for you

Concern	How Charon Gate handles it
Signature verification	HMAC-SHA256 on X-Hub-Signature-256
Your server is down during a push	Retries with backoff; event held until delivery succeeds
CI pipeline slow to start	Charon Gate acknowledges GitHub immediately; forwards asynchronously
All retries exhausted	DLQ entry + Slack/email alert
Duplicate delivery (GitHub retries)	Deduplication via X-GitHub-Delivery header

Recommended events to capture

For CI/CD pipelines:

push
pull_request
check_run
check_suite
workflow_run

For repository management tools:

create
delete
repository
member
team

For review bots and automation:

pull_request
pull_request_review
issue_comment
issues

Troubleshooting

GitHub shows failed to deliver but event appears in Charon Gate → Charon Gate acknowledged the event (202). The failure shown in GitHub means the initial delivery to Charon Gate worked, but GitHub is still showing the original delivery status. Check the Charon Gate event detail for the actual forward delivery status.

Events showing signature_verification_failed → Confirm the secret you entered in Charon Gate matches what you set in GitHub exactly (no extra spaces or newlines).

Push events not appearing → Verify the GitHub webhook shows Recent Deliveries with green checkmarks. If GitHub can't reach the Charon Gate ingest URL, check for network/firewall issues.