# Fix GitHub webhook ping event timing out

## TL;DR
Ping timeouts mean GitHub cannot reach your webhook URL at all. Check that the URL is publicly reachable, responds fast, and is not blocked by a firewall or auth. The ping is a simple POST; if it times out, delivery of real events will too.

## The error
```text
GitHub webhook: Ping event failed
Delivery timed out. We could not reach the webhook URL in time.
```

## Use this skill
Agent? Search Vectle for this error:
```bash
curl -s "https://vectle.com/api/v1/search?q=github webhook ping event timeout"
```

## Fix it

### Step 1: Hit the URL yourself from outside

```bash
From a machine outside your network, POST to the webhook URL and time it.
```

Expected: You see whether it is reachable and how slow it is.

### Step 2: Check firewall and security groups

```bash
Confirm the port is open to the internet or to GitHub's hook IP ranges.
```

Expected: Traffic can reach the endpoint.

### Step 3: Remove auth from the ping path

```bash
GitHub's ping carries no credentials. Exempt the webhook path from auth or return 200 for pings.
```

Expected: The endpoint answers 200 without credentials.

### Step 4: Make the handler respond fast

```bash
Return 200 immediately and process async, as with any webhook receiver.
```

Expected: Response time is well under the timeout.

### Step 5: Redeliver the ping

```bash
In the repo or org webhook settings, redeliver the ping event.
```

Expected: Delivery shows 200 and a green check.

## When this applies

- GitHub webhook pings time out
- You just created the webhook and it never went green
- Webhooks worked and broke after an infra change

## When it doesn't

- The ping delivers but events never fire (check the event selection)
- Deliveries 401 or 403 (check auth on the path)
- The secret verification fails (check the webhook secret)

## Compatibility

GitHub webhooks. Repo, org, and GitHub App webhooks.

## Variant phrasings

### github webhook delivery timed out

Same failure on real events. Reachability and speed are the two things to check.

### github ping event failed webhook

A failed ping blocks confidence in the whole webhook. Fix the ping first.

### github webhook could not reach url

DNS, firewall, and auth are the three usual blockers, in that order.

## Why it happens

The ping is GitHub's connectivity check: a plain POST it expects to get a fast 200 for. Timeouts mean the request never completed, which points at network reachability, a blocking firewall, an auth wall, or a handler slower than the timeout. Real events will fail the same way.

## Edge cases

- Tunnels like ngrok sleep or expire; a dead tunnel looks exactly like this
- Corporate egress proxies can block GitHub's ranges; check with your network team
- A handler that does signature verification synchronously is fine; one that calls a slow DB is not

## If it still fails

- Reproduce with one API call in isolation, outside the agent, to separate platform issues from agent issues.
- Check the platform status page and changelog; OAuth and webhook behaviors change without warning.
- Capture the full request and response with timestamps for the vendor ticket, redacting credentials.
- Test in a second workspace or sandbox to rule out workspace-specific policy blocks.
- If the integration is business-critical, build the fallback now: cached data, a manual trigger, or a second provider.

## Prevention

- Store OAuth credentials in a secrets manager with rotation reminders.
- Build the reconnect flow before you need it; every integration gets revoked eventually.
- Log token ages so expiring grants are visible ahead of time.
- Keep a sandbox integration for testing config changes.
- Document the required scopes per integration so reinstalls request the right ones.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_fXfhtb7ItNoslUkS4bPrKQ