Integrations
The Integrations admin combines API key management and
webhook management in a single screen with two tabs. Find it at
Admin → Integrations. Route: /admin/integrations.
API Keys tab
API keys are non-interactive credentials for service-to-service calls. They're scoped to an account and carry the same permission-rule profile system that user memberships do.
Create
Click + New API key, give it a name and an optional
expiry, optionally pick a permission rule profile. The API
returns the secret token once in the create response —
prefix rk_…. Copy it now, the server only stores its hash.
Use
Send the secret on every request:
X-API-Key: rk_your_secret_token_here
The middleware looks the key up by hash, sets the request's
auth context the same way a JWT would, and applies any
permission profile attached to the key.
Revoke
The list view has a delete affordance per key. Deleted keys 401 on the next request — there's no grace period. The list also shows last-used timestamp so you can spot dormant keys.
| API path | Purpose |
|---|---|
GET /api-keys | List (no secrets returned) |
POST /api-keys | Create — secret returned in response only |
PATCH /api-keys/:id | Rename / change profile / set expiry |
DELETE /api-keys/:id | Revoke |
Webhooks tab
Webhooks deliver entity-change events to your URL with an HMAC signature.
Create
Click + New webhook. You'll need:
- URL — where to POST (any HTTPS endpoint that can verify HMAC)
- Events — pick which entity changes you want
(
lap.created,setup.updated,issue.resolved, …) - Secret — the HMAC key. The UI generates a strong default; you can paste your own if you have a secret manager.
Delivery
When an event fires the API POSTs to your URL with:
- Header
X-Race-Signature: sha256=<hex>— HMAC of the body - Header
X-Race-Event: <event.name> - Header
X-Race-Webhook-Id: <uuid> - JSON body
{ event, accountId, entity }
Verify the signature using the same secret you saved on create. Any 2xx response is a success.
| API path | Purpose |
|---|---|
GET /webhooks | List |
POST /webhooks | Create |
PATCH /webhooks/:id | Update URL / events / status |
DELETE /webhooks/:id | Delete |
What you can do today
- Issue, rename, revoke API keys
- Attach a permission profile to a key
- Subscribe to entity-change events with HMAC-signed delivery
What's coming
- Delivery history pane — last 50 attempts per webhook with request/response, failure reasons, manual retry
- Per-event filtering — subscribe only when an issue's
severity ≥
major, etc. - OAuth client provisioning — for inbound integrations that need a per-user token, not a service token
- Signed test deliveries — "send a synthetic event" button