Webhooks

Brume ships outbound webhooks. You register an HTTP endpoint, and Brume posts events to it with an HMAC signature so you can verify the request came from Brume.

How delivery works

1. You register a webhook with a destination URL and an event list.
2. Brume's delivery worker picks up events and POSTs them to your URL.
3. Each delivery is an independent HTTP POST with its own signature and delivery ID.
4. Failed deliveries are retried with backoff; every attempt is recorded and visible under the webhook's delivery log.

Events

The event catalog is intentionally small during soft launch:

Rate-limiting is a synchronous request/response product — the verdict is already in your caller's hand, so there is no per-check event stream. The webhook surface exists for operational notifications and will grow as the product does. Registering an unknown event name is rejected.

Registering a webhook

curl -X POST https://api.brume.run/v1/webhooks \
  -H "Authorization: Bearer $BRUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/brume",
    "events": ["webhook.test"]
  }'

The response includes a secret — the HMAC signing key, returned exactly once. Store it with the webhook.

Verifying signatures

Every delivery carries three headers:

Verify by computing HMAC-SHA256 of the raw request body with your secret and comparing to the signature in constant time:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody: Buffer, signatureHeader: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(signatureHeader);
  return a.length === b.length && timingSafeEqual(a, b);
}

Use X-Brume-Delivery-Id to deduplicate: retries reuse the same delivery ID.

Managing webhooks

• GET /v1/webhooks — list registrations
• DELETE /v1/webhooks/:id — remove a registration
• GET /v1/webhooks/:id/deliveries — delivery history with statuses
• POST /v1/webhooks/:id/test — fire a webhook.test event

Webhook management requires the manage_project scope.