Skip to main content
Webhooks push real-time notifications to your server when things happen in Bluum — orders filling, transfers completing, KYC decisions landing. Use them instead of polling to build responsive integrations.

​
Event model

Every event is named {domain}.{action} — for example order.filled, transfer.deposit.completed, kyc.verification.approved. Subscribe to a whole domain with a wildcard: order.*, transfer.*. List the available event types with GET /v1/webhooks/event-types.

​
Registering an endpoint

Create a webhook with POST /v1/webhooks, passing your url and the events you want in eventTypeNames (an array of event names or wildcards): 
{
  "name": "Production webhook",
  "url": "https://your-app.com/webhooks/bluum",
  "eventTypeNames": ["order.*", "transfer.*"]
}
The registration field is eventTypeNames — not events. Manage endpoints with GET /v1/webhooks, PATCH /v1/webhooks/{webhook_id}, and DELETE /v1/webhooks/{webhook_id}.
Webhook management is a tenant-level operation. Investor-scoped API keys are rejected on these routes.

​
Delivery and retries

Webhook delivery
Bluum sends a POST with the event payload and expects a 2xx promptly. If your endpoint fails or times out, delivery is retried with exponential backoff; after retries are exhausted the event is parked for replay. Handle delivery defensively:
  • Respond fast — return 2xx quickly and process asynchronously.
  • Expect duplicates — the same event may arrive more than once; dedupe on the event id.
  • Verify signatures — validate the signature header so you only act on genuine Bluum requests.
  • Use HTTPS — required for production endpoints.
For registering an endpoint and consuming events step by step, see the journey guide: Handle webhooks. Webhook schemas are in the API reference.