Dead LetterWebhook recoveryGitHub Integration Guide
Docs Home
Back to Docs
GITHUB

Redirecting GitHub Webhooks Through Dead Letter

GitHub sends webhook events for repository activity such as pushes, pull requests, and issue updates. This guide shows you how to route those events through Dead Letter to ensure zero data loss during deployment windows or outages.

Prerequisites

  • A Dead Letter account with at least one configured endpoint
  • Admin access to the GitHub repository or organization
  • Your Dead Letter Ingestion URL (found in the endpoint details page)

Step 1: Navigate to Repository Webhooks

Open your repository on GitHub. Click the Settings tab, then select Webhooks in the left sidebar. Click Add webhook in the top right.

Note: For organization-owned repositories, you may need to configure the webhook at the organization level under Settings → Webhooks to manage webhooks across multiple repos.

Step 2: Configure Webhook Settings

Webhook Configuration

  • Payload URL: Enter your Dead Letter Ingestion URL: https://api.deadletterhub.io/ingest/<your-slug>
  • Content type: Select application/json
  • Secret: (Optional but recommended) Enter a secret token. Dead Letter will forward the GitHub HMAC signature header (x-hub-signature-256) unchanged so your server can still verify payload authenticity.
  • SSL verification: Enable Enable SSL verification (Dead Letter uses valid TLS certificates)

Step 3: Select Events

Choose which events trigger the webhook. You have three options:

Option A: Send me everything

Forwards all repository events. Best for comprehensive auditing but generates high volume.

Option B: Let me select individual events

Recommended. Select only the events your application processes:

  • push — Triggered on git push to the repository
  • pull_request — Opened, closed, reviewed, merged
  • issues — Created, updated, closed
  • workflow_run — GitHub Actions workflow events
  • release — Published or edited releases

Step 4: Configure Your Destination Server

Your destination server should process the forwarded webhooks using the original GitHub headers that Dead Letter preserves:

HeaderDescription
x-github-eventGitHub event type (e.g., push, pull_request)
x-hub-signature-256HMAC-SHA256 signature for payload verification
x-dead-letter-event-idUnique event ID for deduplication
x-dead-letter-retry-countCurrent retry attempt number

Step 5: Verify Delivery

After saving, GitHub sends a ping event to verify the webhook works. Check your Dead Letter dashboard Event Logs to confirm ingestion. You can also manually trigger test events (e.g., push to a test branch) to verify end-to-end delivery.

Troubleshooting

  • Webhook showing red in GitHub? GitHub marks the webhook as failed if the endpoint returns non-2xx. Verify the Dead Letter endpoint is active and the ingestion slug is correct.
  • Recent deliveries showing errors? In the GitHub webhook settings page, scroll down to see Recent Deliveries. Check the response tab for Dead Letter's response code and body.
  • Signature mismatch on your server? Verify using GitHub's original x-hub-signature-256 header and the secret configured in GitHub, not the Dead Letter HMAC secret.