> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webhooktrap.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Capture GitHub webhooks and prove your handler against forged and unsigned deliveries, bursts and GitHub's 10-second limit.

## Point GitHub at your capture URL

**1. Copy your capture URL**

It is on **Arrivals**: `https://in.webhooktrap.dev/c/` followed by a 12-character key.

**2. Add the webhook**

In the repository, open **Settings › Webhooks › Add webhook**. Set **Payload URL** to the capture URL, **Content type** to `application/json`, and set a secret.

**3. Trigger events**

Push a commit, open an issue, or use **Redeliver** on a recent delivery in the webhook's settings.

Webhook Trap recognises a GitHub delivery by its `X-GitHub-Event` header, takes the event type from that header and the event id from `X-GitHub-Delivery`, and groups events by repository and organization.

## Configure the agent

```yaml webhooktrap.yml theme={"theme":{"light":"github-light","dark":"github-dark"}}
target: http://127.0.0.1:3000/webhooks/github
provider: github
secret: env:GITHUB_WEBHOOK_SECRET
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export GITHUB_WEBHOOK_SECRET=...
webhooktrap agent
```

If you leave out `secret`, the agent looks for `GITHUB_WEBHOOK_SECRET`, the name in the GitHub pack.

> [!NOTE]
>
> Your signing secret stays on your machine. `webhooktrap.yml` holds only the name of the environment variable (`secret: env:NAME`). The agent reads the value when it signs a delivery, strips every known secret variable from the environment of probe and reset commands, and refuses to write or upload a run document that contains the secret. The server learns the variable's name, never its value.

GitHub signs no timestamp, so the body and its original `X-Hub-Signature-256` still verify later. Without the secret the agent sends valid deliveries with the captured signature header; with it, it re-signs them.

## What the scenarios do for GitHub

| Scenario | For GitHub |
| - | - |
| Once | Each selected event. |
| Twice | `n/a (not verified for GitHub)`: the GitHub pack's duplicate rule is not verified yet. |
| Shuffled | The events in reverse order. Needs 2 or more events. |
| Late | `n/a (provider signs no timestamp)`. |
| Retry after error | `n/a (GitHub doesn't retry automatically)`. |
| Tampered | The body with one field changed, signed for the original body. The GitHub pack names no field, so the first numeric field whose name contains `amount`, `total`, `price` or `quantity` changes; if there is none, `"_webhooktrap_tampered":true` is added. |
| Unsigned | The first event with `X-Hub-Signature-256` and `X-Hub-Signature` removed. |
| Burst | Every selected event at once (two copies when you select one). |
| Slow budget | One more delivery, measured against the 10 s budget. |

The 10 s budget comes from GitHub's docs. A `budget:` above it in `webhooktrap.yml` is refused as a configuration error, because it would hide a failure GitHub documents.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.