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.

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.

curl -X POST https://alumia.com/api/v1/webhooks \
-H "Authorization: Bearer alm_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{ "name": "Stripe events", "events": ["payment_intent.succeeded"] }'

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