.git — Custom Webhooks

📡 Overview

.git webhooks allow your applications or third-party services to subscribe to repository events. When a triggered event occurs, .git sends a `POST` request to your configured endpoint with a JSON payload containing event metadata.

Webhooks are ideal for:

Triggering external CI/CD pipelines or build servers
Sending notifications to Slack, Discord, or Microsoft Teams
Syncing deployment status to monitoring dashboards
Automating infrastructure provisioning on branch creation

⚡ Quick Setup

Create a webhook endpoint in three steps:

bash

# 1. Expose your local dev server (optional)
npx localtunnel --port 3000

# 2. Register the webhook via API
curl -X POST https://api.git.dev/v1/webhooks \
  -H "Authorization: Bearer $GIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/git/webhook",
    "events": ["push", "deploy.success"],
    "secret": "your-super-secret-string"
  }'

# 3. Verify delivery
tail -f /var/log/app/webhook.log

Alternatively, configure webhooks directly from your project dashboard under Settings → Integrations → Webhooks.

📦 Payload Format

All webhook payloads follow a consistent envelope structure:

json

{
  "id": "evt_8f9a2b3c4d5e6f7g",
  "type": "push",
  "timestamp": "2025-03-15T14:32:00Z",
  "source": {
    "type": "repository",
    "id": "repo_abc123",
    "name": "backend-api",
    "owner": "acme-corp"
  },
  "data": {
    "ref": "refs/heads/main",
    "sha": "a1b2c3d4e5f6",
    "committer": "dev@example.com",
    "files_changed": ["src/auth.js", "config/deploy.yml"]
  },
  "signature": "sha256=9a8b7c6d..."
}

The data object varies by event type. See the Event Reference for exact schemas.

🔔 Trigger Events

Event	Description	Frequency
push	Code committed to a tracked branch	On commit
deploy.start	Deployment pipeline initiated	On trigger
deploy.success	Production deployment completed	On finish
deploy.fail	Deployment failed or rolled back	On error
review.created	New pull/merge request opened	On creation
review.approved	Review passed CI checks	On approval

🔒 Security & Signatures

Always verify webhook payloads to prevent spoofing. .git signs every request using HMAC-SHA256 with your configured secret.

Verifying Signatures (Node.js)

javascript

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-git-signature'];
  const payload = JSON.stringify(req.body);
  const secret = process.env.WEBHOOK_SECRET;

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

  if (signature !== `sha256=${hmac}`) {
    return res.status(401).send('Invalid signature');
  }

  processPayload(req.body);
  res.status(200).send('OK');
});

Headers sent with every request:

X-Git-Signature: HMAC-SHA256 hash of the payload
X-Git-Event: The event type (e.g., push)
X-Git-Delivery: Unique webhook delivery ID
X-Git-Timestamp: Unix epoch timestamp

🔄 Retry Policy

.git guarantees at-least-once delivery. If your endpoint doesn't respond with a 2xx status within 10 seconds, we retry using exponential backoff:

Attempt 1: Immediately
Attempt 2: 5 minutes later
Attempt 3: 30 minutes later
Attempt 4: 2 hours later
Attempt 5: 6 hours later

After 5 failed attempts, the webhook is marked as disabled and you'll receive an alert. Failed payloads are retained for 7 days and can be manually resent from the dashboard.

❓ FAQ

Use the branch_filter parameter in your webhook config. Accepts exact names or glob patterns (e.g., main, release/*, feat-*). Events from non-matching branches won't trigger a payload.

.git supports up to 1,000 webhook deliveries per minute per organization. If you exceed this, requests are queued and delivered in order. Pro & Enterprise plans include priority queuing and dedicated delivery channels.

Yes. Navigate to Project Settings → Webhooks, locate your endpoint, and toggle Paused. Paused webhooks retain all configuration but skip delivery until re-enabled. Paused state resets automatically after 14 days of inactivity.

🛠 Troubleshooting

Common issues and resolutions:

403 Forbidden: Ensure your secret matches exactly. Case-sensitive. Check for trailing whitespace.
Timeout (504): Your endpoint must respond within 10s. Offload heavy processing to a queue (Redis, SQS, BullMQ).
Duplicate payloads: Webhooks are at-least-once. Implement idempotency using the X-Git-Delivery header.
Certificate errors: Self-signed certs are not accepted. Use Let's Encrypt or enterprise CA certificates.

bash

# Test webhook connectivity from CLI
curl -X POST https://your-app.com/git/webhook \
  -H "Content-Type: application/json" \
  -H "X-Git-Event: push" \
  -d '{"test": true}'

# Check delivery logs via API
curl https://api.git.dev/v1/webhooks/deliveries \
  -H "Authorization: Bearer $GIT_TOKEN" \
  | jq '.[-5:]'