Webhooks

Webhooks in Alumia are inbound receivers: each webhook resource owns a public URL that third-party systems can POST to. Alumia validates the signature, records the event, and routes it to org-level handlers. The same record also stores an optional outbound url so the platform can forward events to your service.

Inbound webhook POST bodies are capped at 256 KB by default (lib/api/request-body-limits.ts). Management routes (POST / PATCH / DELETE on /webhooks and /webhooks/:id, plus test/retry/rotate) require a stepped-up browser session and use the standard 128 KB JSON cap. API keys are rejected with 403 "Webhook management requires a browser session".

Endpoints

List

GET /api/v1/webhooks returns webhook records ordered by createdAt desc. Each item:

{
  "id": "uuid",
  "name": "string",
  "url": "https://...",
  "source": "custom",
  "description": "string|null",
  "events": ["..."],
  "status": "active",
  "enabled": true,
  "deliveryCount": 0,
  "lastDeliveryAt": null,
  "createdAt": "...",
  "updatedAt": "...",
  "receiveUrl": "https://alumia.com/api/v1/webhooks/receive/<id>"
}

receiveUrl is computed from the request origin and is the URL third parties should POST to.

Create

POST /api/v1/webhooks

The response includes the plaintext secret once. Store it securely; the server only retains an encrypted copy and a hash.

Create and rotate webhooks from the dashboard or another browser-session flow after step-up. API-key curl requests cannot create or rotate webhook secrets.

Update

PATCH /api/v1/webhooks/:id accepts any subset of name, url, source, description, events, enabled, status ("active" or "paused"/"disabled"). Setting url to null or "" resets it to the receive URL. Setting status keeps enabled in sync.

Delete

DELETE /api/v1/webhooks/:id performs a hard delete. Returns { "deleted": true }.

Rotate secret

POST /api/v1/webhooks/:id/rotate generates a new secret pair, persists the encrypted form and hash, and returns the new plaintext once. Old signatures stop verifying immediately.

Events and deliveries

• GET /api/v1/webhooks/:id/events — Events recorded for this webhook.
• GET /api/v1/webhooks/:id/deliveries — Outbound delivery attempts (status, retry count, response).
• GET /api/v1/webhooks/events — Recent events across all webhooks in the org (up to 100), joined to webhook name.

Receiving and verification

POST /api/v1/webhooks/receive/:webhookId accepts the third-party payload, verifies the signature using the stored hash, and stores the event. This route does not require an Alumia API key — authentication is signature-based.

POST /api/v1/webhooks/verify lets you check a signed payload independently of the receive endpoint.

POST /api/v1/webhooks/test posts a synthetic event so you can wire end-to-end without involving the upstream provider.

Errors