GitHub Webhook Integration

This document covers how to configure and use the GitHub webhook integration in izri to automatically trigger repository analysis on push events.

Overview

When a GitHub push event is delivered to the webhook endpoint, izri:

1. Validates the HMAC-SHA256 signature using the project's configured secret.
2. Checks whether the push matches the configured trigger conditions (branch list, file patterns).
3. Creates a webhook_events record for audit/retry tracking.
4. If conditions match, creates a project_analyses record and queues repository analysis.

Webhook endpoint

POST /api/webhooks/github/:projectId

Required headers (sent automatically by GitHub)

Setting up a webhook in GitHub

1. Navigate to your GitHub repository → Settings → Webhooks → Add webhook.
2. Set Payload URL to:

   https://<your-api-host>/api/webhooks/github/<projectId>
   

3. Set Content type to application/json.
4. Enter the Secret generated by izri (see Configuring via tRPC below).
5. Under Which events would you like to trigger this webhook?, choose Just the push event (other events are acknowledged but not acted on).
6. Click Add webhook.

Configuring via tRPC

All webhook management is exposed through the webhooks tRPC router.

Create / update webhook config

const result = await trpc.webhooks.configure.mutate({
  projectId: '01JXXXXXXXXXXXXXXXXXXXXXXX',
  branches: ['main', 'develop'],   // empty = all branches
  filePatterns: ['src/**/*.ts'],   // empty = any file
})

// result.secret  ← copy this into your GitHub webhook settings (shown once only)
// result.configId

Get current config (secret excluded)

const config = await trpc.webhooks.getConfig.query({
  projectId: '01JXXXXXXXXXXXXXXXXXXXXXXX',
})
// { active, branches, filePatterns, configId, createdAt, updatedAt }

Enable / disable webhook

await trpc.webhooks.setActive.mutate({
  projectId: '01JXXXXXXXXXXXXXXXXXXXXXXX',
  active: false,
})

Rotate secret

If you suspect your secret has been compromised, rotate it. After rotating, update the secret in the GitHub webhook settings.

const { secret } = await trpc.webhooks.rotateSecret.mutate({
  projectId: '01JXXXXXXXXXXXXXXXXXXXXXXX',
})
// Update GitHub webhook settings with the new secret

List delivery events

const { events } = await trpc.webhooks.listEvents.query({
  projectId: '01JXXXXXXXXXXXXXXXXXXXXXXX',
  limit: 20,
  // optional: status: 'FAILED' | 'PROCESSED' | 'PENDING' | 'SKIPPED' | 'ABANDONED'
})

Delete webhook config

await trpc.webhooks.delete.mutate({
  projectId: '01JXXXXXXXXXXXXXXXXXXXXXXX',
})

Trigger conditions

Branch filter

File pattern filter

Patterns use * (single-directory wildcard) and ** (cross-directory wildcard).

The filter is evaluated against the union of added, modified, and removed files across all commits in the push.

Security

• Signatures are validated using HMAC-SHA256 (Web Crypto API; no native addon required).
• Comparison uses a constant-time byte-by-byte XOR check to prevent timing attacks.
• Deliveries without a valid X-Hub-Signature-256 header are rejected with HTTP 401.
• Duplicate deliveries (same X-GitHub-Delivery) are idempotent — the second delivery is ignored.

Error handling and retry logic

Failed webhook events are retried up to 3 times with exponential backoff:

After 3 failed attempts the event is marked ABANDONED.

The retry function retryFailedWebhookEvents() should be called by a periodic background job (e.g. every minute):

import { retryFailedWebhookEvents } from '@izri/trpc/services/webhookService'

// In your cron / background worker:
const { retried, abandoned } = await retryFailedWebhookEvents()

Event status reference

Database tables

webhook_configs

Stores one configuration per project.

webhook_events

Audit log of every delivery received.