Webhooks

Webhooks deliver selected repository events to an HTTPS endpoint you control. Repository administrators manage subscriptions through the versioned API. The current repository settings pages do not include a webhook editor.

Create a subscription

Send an authenticated POST to /api/v1/repos/{owner}/{repo}/webhooks with a JSON body containing url, secret, and events. For example, events can include push, issues, or pull_request. The API requires a credential with repo.admin scope and repository administration permission. The target URL must be HTTPS and pass the platform's target validation. Keep the signing secret outside source control and send it only from a trusted client; do not put it in a URL or shell history. See API and authentication for credential guidance.

Use GET /api/v1/repos/{owner}/{repo}/webhooks to list subscriptions. The create response returns the subscription ID, which you need to inspect its deliveries.

Receive safely

Read the raw request body before parsing it, check the delivery signature, and reject a request whose signature does not match. The platform signs deliveries in the X-Hub-Signature-256 header. Use a constant-time comparison and the secret configured for that webhook.

Respond quickly after recording the delivery. Process longer tasks asynchronously, and make processing idempotent because a delivery can be retried. Keep delivery IDs in a bounded retention store so duplicate deliveries do not repeat side effects.

Diagnose delivery

Repository administrators can use GET /api/v1/repos/{owner}/{repo}/webhooks/{webhookId}/deliveries to inspect recent attempts and response codes. The API uses bounded page and limit query parameters. There is no repository delivery-view page yet. Avoid returning secrets or customer data in endpoint error responses. If you rotate a secret, coordinate the receiver and webhook configuration before removing the old key.

For API credentials used by a webhook worker, see API and authentication.