Repo Cat

Webhooks

Webhooks allow you to receive HTTP POST requests when scan events occur in Repo Cat. This enables real-time integration with your own systems.

Overview

When a scan event occurs (started, completed, failed, or cancelled), Repo Cat sends an HTTP POST request to your configured endpoint with event details in JSON format.

Quick Example

# Enable webhooks via settings API
curl -X PUT "http://repo-cat.futoro.co.uk/api/v1/settings" \
   -H "X-API-Key: your-api-key" \
   -H "Content-Type: application/json" \
   -d '{
     "webhook_url": "https://your-app.com/webhook",
     "webhook_enabled": true,
     "webhook_on_scan_completed": true
   }'

Configuration

Configure webhooks using the Settings API. You can enable webhooks and choose which events to receive.

Settings Fields

FieldTypeDescription
webhook_urlstringYour webhook endpoint URL
webhook_enabledbooleanEnable/disable all webhooks
webhook_on_scan_startedbooleanSend when scan starts
webhook_on_scan_completedbooleanSend when scan completes (default: true)
webhook_on_scan_failedbooleanSend when scan fails
webhook_on_scan_cancelledbooleanSend when scan is cancelled

Event Types

Four event types are available, each with different payload structure.

scan_started

Sent when a scan begins processing.

{
  "id": "evt_123456789_abc123",
  "timestamp": "2026-04-25T12:00:00.000Z",
  "userId": "123",
  "type": "scan_started",
  "data": {
    "scanId": 456,
    "repo": "facebook/react",
    "level": "deep",
    "reference": "main"
  }
}

scan_completed

Sent when a scan finishes successfully.

{
  "id": "evt_123456789_abc123",
  "timestamp": "2026-04-25T12:00:00.000Z",
  "userId": "123",
  "type": "scan_completed",
  "data": {
    "scanId": 456,
    "repo": "facebook/react",
    "level": "deep",
    "reference": "main",
    "result": {
      "metadata": { "stars": 32000 },
      "metrics": { "score": 85 }
    }
  }
}

scan_failed

Sent when a scan encounters an error.

{
  "id": "evt_123456789_abc123",
  "timestamp": "2026-04-25T12:00:00.000Z",
  "userId": "123",
  "type": "scan_failed",
  "data": {
    "scanId": 456,
    "repo": "facebook/react",
    "level": "deep",
    "reference": "main",
    "error": "GitHub API rate limit exceeded"
  }
}

scan_cancelled

Sent when a scan is cancelled.

{
  "id": "evt_123456789_abc123",
  "timestamp": "2026-04-25T12:00:00.000Z",
  "userId": "123",
  "type": "scan_cancelled",
  "data": {
    "scanId": 456,
    "repo": "facebook/react",
    "level": "deep",
    "reference": "main"
  }
}

Request Headers

Each webhook request includes these headers:

HeaderDescription
Content-Typeapplication/json
User-AgentRepoCat-Webhook/1.0
X-Webhook-EventEvent type (e.g., scan_completed)
X-Webhook-DeliveryUnique delivery ID

Security

Since webhooks send data to your endpoint, verify the request originates from Repo Cat.

Verifying Source

Only accept requests from your known Repo Cat server IP. Check the Remote-Addr header to filter by IP address.

Example Verification

// Node.js example
const ALLOWED_IPS = ['your-server-ip'];

app.post('/webhook', (req, res) => {
  const clientIp = req.socket.remoteAddress;
  
  if (!ALLOWED_IPS.includes(clientIp)) {
    return res.status(403).send('Forbidden');
  }
  
  const event = req.body;
  console.log('Received:', event.type);
  res.status(200).send('OK');
});

Retry Behavior

If your endpoint returns a non-2xx status code or times out, Repo Cat retries up to 3 times with increasing delays.

  • Retry 1: After 1 second
  • Retry 2: After 3 seconds
  • Retry 3: After 10 seconds

Client errors (4xx status codes) are not retried. Only server errors (5xx) trigger retries.

Note: Each retry uses a new delivery ID. Check the X-Webhook-Delivery header to detect duplicates.

Troubleshooting

Webhooks Not Being Sent

  • Verify webhook_enabled is true
  • Ensure the event is enabled (e.g., webhook_on_scan_completed)
  • Check your webhook_url is a valid HTTPS endpoint

Endpoint Not Receiving Requests

  • Verify firewall allows incoming HTTP/HTTPS
  • Check your server logs for blocked requests
  • Ensure your endpoint accepts POST requests

Requests Timing Out

  • Repo Cat has a 30-second timeout
  • Process webhooks asynchronously in your handler
  • Return 200 quickly, then process in background

Next Steps

PreviousMCP Server