✓ Webhooks

Connect your workflows to external services. Receive real-time HTTP notifications when events occur in your .git repositories, pipelines, or deployments.

Overview

Webhooks allow .git to send HTTP POST requests to your configured endpoints whenever specific events trigger in your workspace. They're ideal for integrating with Slack, Discord, custom dashboards, monitoring tools, or internal APIs.

💡 Tip

All webhook requests include a X-Git-Signature header for verification. Always validate payloads before processing.

Each webhook can be scoped to specific repositories, branches, or event types. Failed deliveries are automatically retried up to 5 times with exponential backoff.

Setup & Configuration

Creating a Webhook

  1. Navigate to Project Settings → Webhooks
  2. Click + New Webhook
  3. Enter your payload URL (must support HTTPS)
  4. Select trigger events and optionally scope to branches/repos
  5. Generate a signing secret and save

Testing Delivery

Use the Test Webhook button to send a sample payload immediately. You can view delivery logs, retry failed requests, and inspect raw headers.

Event Types

Configure your webhook to listen to specific actions. Combine multiple events or use * for all triggers.

Event Description Scope
push One or more commits pushed to a branch Repository
pull_request.* PR opened, closed, merged, or reviewed Repository
deploy.success Production deployment completed successfully Environment
deploy.failed Deployment hit an error or timeout Environment
workflow.completed CI/CD pipeline finished all steps Pipeline
member.added New collaborator granted access Organization

Payload Structure

Webhook payloads are sent as JSON with Content-Type: application/json. Each payload includes metadata, event context, and resource details.

{
  "id": "evt_8f3a9c21b4e5",
  "type": "push",
  "timestamp": "2025-09-10T14:23:05.123Z",
  "repository": {
    "id": "repo_9281",
    "name": "frontend-app",
    "full_name": "acme/frontend-app",
    "visibility": "private"
  },
  "sender": {
    "id": "usr_442",
    "login": "alex.dev",
    "email": "alex@acme.dev"
  },
  "payload": {
    "ref": "refs/heads/main",
    "commits": [
      {
        "id": "a1b2c3d4e5",
        "message": "feat: add dark mode toggle",
        "author": "alex.dev",
        "timestamp": "2025-09-10T14:22:41Z"
      }
    ],
    "comparison_url": "https://git.dev/acme/frontend-app/compare/v1.2.0...v1.3.0"
  }
}

⚠️ Payload Limits

Maximum payload size is 1MB. Large diffs or commit histories are truncated. Use pagination links in the comparison_url for full data.

Security & Signatures

Every webhook request includes an HMAC-SHA256 signature to verify authenticity. The signature is calculated using your webhook secret and the raw request body.

Header Format

Content-Type: application/json
X-Git-Event: push
X-Git-Signature: sha256=9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
X-Git-Timestamp: 1725993785

Verification Example (Node.js)

import crypto from 'crypto';

function verifyWebhook(req, secret) {
  const sig = req.headers['x-git-signature']?.replace('sha256=', '');
  const payload = JSON.stringify(req.body);
  const timestamp = req.headers['x-git-timestamp'];

  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(timestamp + payload);
  const computed = hmac.digest('hex');

  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(computed));
}

Always validate the signature before processing. Reject requests with mismatched or missing signatures.

Troubleshooting

Common Issues

  • SSL/TLS Errors: Endpoints must support valid, publicly trusted certificates. Self-signed certs are rejected.
  • Timeouts: .git expects a 2xx or 3xx response within 10 seconds. For long-running tasks, return 202 Accepted immediately.
  • Duplicate Events: Webhooks may deliver events twice during network recovery. Use the unique id field to deduplicate.
  • Payload Decoding: Ensure your server parses application/json correctly. Raw bodies are required for signature verification.

Delivery Logs

Access Project Settings → Webhooks → Deliveries to view request/response payloads, status codes, latency, and retry attempts. Export logs as JSON or CSV.

API Reference

Manage webhooks programmatically via our REST API. Requires webhook:read or webhook:write scope.

GET /repositories/:repo_id/webhooks
POST /repositories/:repo_id/webhooks
GET /webhooks/:webhook_id/deliveries
POST /webhooks/:webhook_id/deliveries/:delivery_id/attempts
DELETE /webhooks/:webhook_id

See the full API documentation for request/response schemas, pagination, and rate limits.