> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bluumfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Event model, naming, registration, delivery, and signature verification.

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):

```json theme={null}
{
  "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}`.

<Note>
  Webhook management is a tenant-level operation. Investor-scoped API keys are
  rejected on these routes.
</Note>

## Delivery and retries

<Frame>
  <img src="https://mintcdn.com/bluumfinance/L5Dm3BN-WAZqlyQf/images/diagrams/webhook-delivery.svg?fit=max&auto=format&n=L5Dm3BN-WAZqlyQf&q=85&s=d828c3fdab437f91e74c4618c0559507" alt="Webhook delivery" width="1200" height="340" data-path="images/diagrams/webhook-delivery.svg" />
</Frame>

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.

<Note>
  For registering an endpoint and consuming events step by step, see the journey guide:
  [Handle webhooks](/get-started/journey/webhooks). Webhook schemas are in the
  [API reference](/api-reference/introduction).
</Note>