Webhooks
Send an HTTP POST to your own service when branches and tags change, verify it with an HMAC signature, and check the delivery log.
A webhook sends an HTTP POST to a URL you choose whenever branches or tags change in a repository:
"Receive HTTP POST notifications when events happen in this repository." Webhooks are set up per
repository, in Settings → Webhooks.
Add a webhook
- Open the repository's Settings → Webhooks and click ADD WEBHOOK →.
- Fill in:
- Payload URL: where gitdb.co sends the
POST, for examplehttps://example.com/webhook. - Secret (for HMAC signature verification): optional, but recommended. With a secret, every delivery carries a signature you can check. See Verify the signature.
- Events (comma-separated): which events to send. All five are filled in by default:
push,branch_create,branch_delete,tag_create,tag_delete.
- Payload URL: where gitdb.co sends the
- Click CREATE WEBHOOK →.
The webhook appears in the list with its URL, its events, its status (Active or Inactive), and a failure count if recent deliveries failed. Each webhook has Deliveries, Test, and Delete buttons.
Events
| Event | Sent when |
|---|---|
push | An existing branch (or tag) is updated to a new commit |
branch_create | A new branch is pushed |
branch_delete | A branch is deleted |
tag_create | A new tag is pushed |
tag_delete | A tag is deleted |
One push that changes several branches or tags sends one event per branch or tag. Deliveries are sent after the push has completed, so a slow or failing webhook never blocks a push.
What gitdb.co sends
Each delivery is an HTTP POST with a JSON body and these headers:
| Header | Value |
|---|---|
Content-Type | application/json |
X-Webhook-Event | The event name, for example push |
X-Webhook-Signature | sha256= followed by the signature in hex. Only sent when the webhook has a secret. |
The JSON body includes:
| Field | Meaning |
|---|---|
event | The event name |
ref | The full ref name, for example refs/heads/main or refs/tags/v1.0 |
before, after | For push: the commit SHA before and after the update |
sha | For branch and tag events: the commit SHA the ref points to (for deletions, the SHA it pointed to) |
timestamp | When the event was sent, in Unix seconds |
Each webhook belongs to one repository, so use the Payload URL (or a path or query parameter you put in it) to tell repositories apart on your side.
Verify the signature
When the webhook has a secret, X-Webhook-Signature is the HMAC-SHA256 of the raw request body,
keyed with your secret, written as lowercase hex after sha256=.
To verify a delivery, compute the same HMAC over the exact bytes you received (before parsing the JSON) and compare it with the header. For example, with OpenSSL:
printf '%s' "$RAW_BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"Reject the delivery if the values don't match. Use a constant-time comparison in your own code.
Test a webhook
Click Test to send a sample push event for refs/heads/main. The sample is delivered to the
repository's active webhooks that subscribe to push. If a webhook doesn't include push in its
events, it won't receive the test.
Check deliveries
Click Deliveries to open Recent deliveries: the latest 20 attempts for that webhook. Each row
shows ✓ (success) or ✗ (failure), the event, the HTTP status your server returned, how long it took,
and an error when there was one. A delivery counts as successful when your server answers with a
2xx status.
Failures and limits
- After 10 failed deliveries in a row, gitdb.co pauses the webhook for one hour. A successful delivery resets the count.
- The Payload URL must be reachable on the public internet. Deliveries to loopback, private network, or link-local addresses are refused.
- For
https://URLs, your server must present a valid, publicly trusted TLS certificate.
Delete a webhook
Click Delete next to the webhook. gitdb.co stops sending to it immediately.