Webhooks

Overview

.git webhooks send HTTP `POST` requests to a configured endpoint whenever a specified event occurs. Each request includes a JSON payload containing event metadata and a cryptographic signature for verification.

Creating Webhooks

You can create webhooks via the dashboard or the REST API:

1. Navigate to Project Settings › Webhooks
2. Click Add Webhook and provide a payload URL (must use `HTTPS`)
3. Select which events should trigger the webhook
4. Generate a secret token for signature verification

Using the API:

curl -X POST https://api.git.dev/v2/webhooks \
  -H "Authorization: Bearer $GIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["push", "pull_request.opened"],
    "secret": "whsec_abc123..."
  }'

Available Events

Filter webhooks to only trigger on specific actions. Combine events using the format `object.action`.

Payload Structure

Every webhook request includes the following headers:

• X-Git-Signature-256: HMAC-SHA256 signature
• X-Git-Event: Event type string
• Content-Type: application/json

Example payload for a push event:

{
  "id": "evt_8f92b1c4d5e6",
  "type": "push",
  "timestamp": "2025-01-15T14:32:10Z",
  "repository": {
    "id": "repo_4a7b2c",
    "name": "my-app",
    "owner": "acme-corp"
  },
  "changes": {
    "ref": "refs/heads/main",
    "before": "a1b2c3d4e5f6",
    "after": "f6e5d4c3b2a1",
    "commits": [
      {
        "id": "c9d8e7f6a5b4",
        "message": "feat: add webhook verification logic",
        "author": "developer@example.com"
      }
    ]
  }
}

Security & Verification

Always verify the webhook signature to ensure requests originate from .git. The signature is generated using HMAC-SHA256 with your webhook secret.

const crypto = require('crypto');

async function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

// Usage in your endpoint
const isAuthentic = await verifyWebhook(
  req.body,
  req.headers['x-git-signature-256'],
  process.env.WEBHOOK_SECRET
);

if (!isAuthentic) {
  return res.status(401).send('Invalid signature');
}

Retry Policy

.git automatically retries failed webhook deliveries using exponential backoff:

• Attempt 1: Immediate
• Attempt 2: 5 minutes
• Attempt 3: 30 minutes
• Attempt 4: 2 hours
• Attempt 5: 12 hours (final attempt)

Retries occur for non-`2xx` responses or network timeouts. After 5 failed attempts, the webhook is marked as FAILED and notifications are suspended until manually re-enabled.

Best Practices

• Idempotency: Design your handlers to safely process duplicate events. Use the id field to track processed webhooks.
• Fast Responses: Acknowledge receipt immediately. Offload heavy processing to background jobs or message queues.
• HTTPS Only: Payload URLs must use valid TLS certificates. Self-signed certificates are rejected.
• Monitoring: Log delivery status and implement alerts for consecutive failures.

Troubleshooting

Common Issues

For advanced debugging, enable Debug Logging in your webhook configuration. Logs are retained for 7 days.