Skip to main content
Webhooks deliver real-time notifications to your server when events occur in Bluum — orders filling, deposits completing, KYC decisions, and more. Use webhooks instead of polling to build responsive integrations.

​
How webhooks work

Event occurs in Bluum → Bluum sends POST to your endpoint → Your server responds 2xx
                                                                    │
                                                              (retry on failure)
  1. Register a webhook endpoint URL and subscribe to event types
  2. When an event occurs, Bluum sends a POST request with the event payload
  3. Your server processes the event and responds with a 2xx status code
  4. If delivery fails, Bluum retries with exponential backoff

​
Event types

Events follow the naming convention {domain}.{action}:
EventDescription
account.createdNew account created
account.updatedAccount details changed
order.acceptedOrder accepted for execution
order.filledOrder fully filled
order.partially_filledOrder partially filled
order.canceledOrder canceled
order.rejectedOrder rejected
transfer.deposit.initiatedDeposit initiated
transfer.deposit.completedDeposit completed, funds available
transfer.deposit.failedDeposit failed
transfer.withdrawal.initiatedWithdrawal initiated
transfer.withdrawal.completedWithdrawal completed
transfer.withdrawal.failedWithdrawal failed
document.approvedKYC document approved
document.rejectedKYC document rejected

​
Wildcards

Subscribe to all events in a domain with *:
  • order.* — All order events
  • transfer.* — All transfer events

​
List available event types

curl -X GET "$BASE_URL/webhooks/event-types" \
  -H "Authorization: Basic $AUTH"

​
Registering a webhook

curl -X POST "$BASE_URL/webhooks" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://your-app.com/webhooks/bluum",
    "eventTypeNames": ["order.*", "transfer.*"]
  }'

​
Managing webhooks

# List webhooks
curl -X GET "$BASE_URL/webhooks" \
  -H "Authorization: Basic $AUTH"

# Update a webhook
curl -X PATCH "$BASE_URL/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Basic $AUTH" \
  -H "Content-Type: application/json" \
  -d '{
    "eventTypeNames": ["order.*", "transfer.*", "account.*"]
  }'

# Delete a webhook
curl -X DELETE "$BASE_URL/webhooks/$WEBHOOK_ID" \
  -H "Authorization: Basic $AUTH"

​
Webhook payload format

{
  "event": "order.filled",
  "timestamp": "2025-06-15T14:30:15Z",
  "data": {
    "id": "ord_x9y8z7a6b5c4d3e2",
    "account_id": "3d0b0e65-35d3-4dcd-8df7-10286ebb4b4b",
    "symbol": "AAPL",
    "side": "buy",
    "status": "filled",
    "filled_qty": "10",
    "average_price": "178.50"
  }
}

​
Retry behavior

If your endpoint doesn’t respond with 2xx within 30 seconds, Bluum retries with exponential backoff:
AttemptDelay
1st retry~1 minute
2nd retry~5 minutes
3rd retry~30 minutes
4th retry~2 hours
5th retry~8 hours
After all retries are exhausted, the event is sent to a dead letter queue. Contact support to replay failed events.

​
Best practices

  • Respond quickly — Return 2xx within 30 seconds. Process the event asynchronously if your logic takes longer.
  • Handle duplicates — The same event may be delivered more than once. Use the event ID for deduplication.
  • Verify signatures — Validate the webhook signature header to ensure the request came from Bluum.
  • Use HTTPS — Webhook endpoints must use HTTPS in production.
  • Monitor failures — Set up alerts if your endpoint starts returning errors.

​
Testing webhooks

In sandbox, webhooks fire exactly like production. Use these tools for local development:
  • webhook.site — Inspect payloads without a server
  • ngrok — Expose your local server to the internet

​
Key endpoints

MethodPathDescription
GET/webhooks/event-typesList available event types
POST/webhooksRegister a webhook
GET/webhooksList webhooks
PATCH/webhooks/{webhook_id}Update a webhook
DELETE/webhooks/{webhook_id}Delete a webhook