Instead of polling for KYC, funding, and order status, register a webhook and let Bluum push events to your endpoint.
Register a webhook
POST /v1/webhooks takes your endpoint url and the events you want in eventTypeNames.
curl -X POST "$BASE_URL/webhooks" \
-H "Authorization: Basic $AUTH" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-app.com/webhooks/bluum",
"eventTypeNames": ["order.filled", "transfer.deposit.completed", "kyc.verification.approved"]
}'
{
"id": "wh_5e6f7g8h9i0j1k2l",
"object": "webhook",
"url": "https://your-app.com/webhooks/bluum",
"event_type_names": ["order.filled", "transfer.deposit.completed", "kyc.verification.approved"],
"status": "active",
"created_at": "2026-07-01T15:10:00Z"
}
The field is eventTypeNames — an array of event names. Do not use events.
Webhook management is a tenant-level operation. Investor-scoped API keys are rejected on these routes — use a tenant-wide key.
List available event types
Fetch the catalog of subscribable events:
curl -X GET "$BASE_URL/webhooks/event-types" \
-H "Authorization: Basic $AUTH"
PATCH /v1/webhooks/{wh_id} and DELETE /v1/webhooks/{wh_id}.
Handle deliveries
Verify the signature
Every delivery is signed. Verify the signature against your webhook secret before trusting the payload. Reject anything that fails verification.
Respond 2xx fast
Return a 2xx quickly. Do the real work asynchronously — queue the event and acknowledge immediately. Slow responses count as failures.
Handle retries idempotently
Failed deliveries are retried with exponential backoff, so the same event can arrive more than once. Deduplicate on the event ID and make your handler idempotent — processing a duplicate must be a no-op.
For local development, point the url at a tunnel such as webhook.site or ngrok to inspect deliveries. 
