title: "Webhooks API"

OpenCodeHub supports outbound webhooks for event-driven integrations with external services like Slack, Discord, CI systems, and custom applications.

Supported Events

Managing Webhooks

Create a Webhook

POST /api/repos/{owner}/{repo}/webhooks

Body:

{
  "url": "https://yourapp.com/webhook",
  "events": ["push", "pull_request.opened"],
  "secret": "your-webhook-secret",
  "active": true
}

List Webhooks

GET /api/repos/{owner}/{repo}/webhooks

Test a Webhook

POST /api/repos/{owner}/{repo}/webhooks/{id}/test

Payload Format

All payloads follow this structure:

{
  "event": "pull_request.opened",
  "repository": {
    "id": "repo_123",
    "name": "my-repo",
    "owner": "alice"
  },
  "sender": {
    "id": "usr_456",
    "username": "alice"
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "data": { ... }
}

Signature Verification

Webhooks are signed with HMAC-SHA256 using the configured secret.

Node.js:

const crypto = require('crypto');

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

Best Practices

1. Use HTTPS URLs only
2. Always verify the HMAC signature
3. Handle duplicate deliveries with idempotency keys
4. Respond quickly (return 200 immediately)
5. Never leave the webhook secret empty