Webhooks

Webhooks let GitBlixt notify external services when activity happens in a repository. When a subscribed event occurs, GitBlixt sends an outbound HTTP POST request with a JSON payload to the URL you configure. Use them to trigger CI systems, chat notifications, deployment hooks, or any service that listens for repository events.

Creating a Webhook

1. Navigate to your repository's Settings → Webhooks page (/<namespace>/<repo>/-/settings/hooks)
2. Click Add webhook
3. Enter the URL that will receive the payloads (must be http:// or https://)
4. Optionally enter a Secret Token used to sign each payload (see below)
5. Select which events should trigger delivery
6. Click Create webhook

New webhooks are enabled by default. By default GitBlixt blocks URLs that point to localhost, loopback, .local hostnames, and private network ranges to guard against server-side request forgery.

Events

A webhook fires only for the events it subscribes to. The supported event types are:

Securing Payloads with a Secret Token

If you set a secret token, GitBlixt signs every request so your receiver can verify it came from GitBlixt and that the body wasn't tampered with. Each delivery includes these headers:

• X-Gitlab-Token — the raw secret token, so you can compare it directly
• X-Hub-Signature-256 — an HMAC-SHA256 of the request body keyed with your secret token, formatted as sha256=<hex>
• X-Gitlab-Event — a human-readable event name (e.g. Push Hook, Merge Request Hook)

To verify the signature, compute the HMAC-SHA256 of the exact raw request body using your secret token as the key, hex-encode it, and compare it to the value after sha256=:

# Pseudocode
expected = "sha256=" + hmac_sha256(secret_token, raw_request_body).hex()
verify(expected == request.headers["X-Hub-Signature-256"])

Every request also sets Content-Type: application/json.

Example Payload

A push event delivers a payload shaped like this:

{
  "object_kind": "push",
  "event_name": "push",
  "before": "0000000000000000000000000000000000000000",
  "after": "a1b2c3d4...",
  "ref": "refs/heads/main",
  "checkout_sha": "a1b2c3d4...",
  "user_id": 1,
  "user_name": "Jane Doe",
  "user_username": "jane",
  "user_email": "jane@example.com",
  "project_id": 42,
  "project": {
    "id": 42,
    "name": "my-repo",
    "path_with_namespace": "jane/my-repo",
    "default_branch": "main"
  },
  "commits": [
    {
      "id": "a1b2c3d4...",
      "message": "Fix the thing",
      "timestamp": "2026-01-01T00:00:00Z",
      "author": { "name": "Jane Doe", "email": "jane@example.com" }
    }
  ],
  "total_commits_count": 1
}

Other event types use an object_kind of merge_request, note, issue, or pipeline, with the relevant data nested under object_attributes.

Delivery History

GitBlixt records every delivery attempt, capturing the event, the payload sent, the HTTP response status, the response body, and whether it succeeded. A delivery counts as successful when the receiver responds with a 2xx status.

Failed deliveries are retried automatically with exponential backoff, up to 5 attempts. Each request has a 10-second response timeout. If a webhook's URL resolves to a private or blocked address at delivery time, the attempt is cancelled and recorded as a failure.

Testing a Webhook

On the Webhooks page, click Test next to any webhook to dispatch a sample push event to its URL. Use the Delete button to remove a webhook.