wikis / GitHub / wiki / concepts / webhooks.md view as markdown report a mistake

Webhooks

Webhooks let GitHub notify an external service when events happen in a repository, organization, or app — the push-based counterpart to polling the REST API.

How they work

1. You register a webhook with a payload URL, a content type (application/json), the events to subscribe to (push, pull_request, issues, release, …, or "everything"), and an optional secret.
2. When a subscribed event fires, GitHub sends an HTTP POST to your URL with a JSON payload describing what happened, plus headers (X-GitHub-Event, X-GitHub-Delivery).
3. Your server responds quickly (2xx) and processes asynchronously.

Security

• Validate the signature. With a secret configured, GitHub signs each delivery (X-Hub-Signature-256, HMAC-SHA256). Verify it before trusting the payload — otherwise anyone who learns your URL can forge events.
• Treat payloads as untrusted input; scope what the handler can do.

Scope & alternatives

• Repository/org webhooks — configured in settings; good for one project or org.
• GitHub App webhooks — an app receives events across all installations, the scalable path for integrations.
• Reliability — GitHub records each delivery; you can inspect payloads/responses and redeliver failed ones for debugging.

For event-driven automation inside GitHub (rather than to an external server), Actions triggered on: events is usually simpler; use webhooks when an outside system needs to react.