Reference: POST /webhooks/scm/:provider
Endpoint that receives GitHub webhooks: how each delivery is signed, the possible responses, and rotating the secret.
GitHub is the only repository provider supported today, so the :provider route parameter is github. This route does not use API keys: incoming payloads are authenticated against the HMAC secret configured for the repository connection.
Headers and events
| GitHub | |
|---|---|
| Signature header | x-hub-signature-256 (format sha256=<hex>) |
| Event header | x-github-event: push or pull_request |
| Delivery id header | x-github-delivery |
| Pull request actions handled | opened, synchronize |
Responses
| Response | Meaning |
|---|---|
202, { "status": "accepted" } | Valid signature. Event stored and queued for processing. |
202, { "status": "duplicate" } | The (provider, delivery id) tuple was already processed. Replays are idempotent. |
202, { "status": "ignored" } | Valid signature for an event type Qably does not ingest. |
404, Unsupported provider "<value>" | The :provider value in the route is not a provider name Qably recognizes. Use github. |
401 | HMAC verification failed against all configured repository connections. |
400 | Malformed request body or invalid JSON. |
Rate limited to 60 requests per minute per instance. Accepted events queue and process asynchronously. The HTTP response acknowledges receipt of the payload rather than completed processing.
Rotating the secret
Each connection holds its own HMAC secret. If the secret configured on the Git provider falls out of sync with Qably, deliveries fail with HTTP 401. Rotating the secret generates a fresh token, persists its encrypted value, and displays the raw string once.
| Action | Endpoint | Required role |
|---|---|---|
| Rotate the webhook secret | POST /projects/:projectId/repository/webhook-secret | owner or admin |
The 201 response returns { "webhookSecret": "<64 hexadecimal characters>" }. Copy this string into your repository webhook configuration before closing the dialog. The former secret is invalidated immediately. Calling this endpoint on a project without a linked repository returns 404.
Important: Secret rotation is also accessible from the Repository tab in project settings. Payloads delivered between secret generation and updating the provider will fail with 401 and should be redelivered from your Git host webhook logs.