> ## 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

> Register a webhook, verify signatures, and handle retries idempotently.

Instead of polling for KYC, funding, and order status, register a webhook and let Bluum push events to your endpoint.

<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 and retry flow" width="1200" height="340" data-path="images/diagrams/webhook-delivery.svg" />
</Frame>

## Register a webhook

`POST /v1/webhooks` takes your endpoint `url` and the events you want in `eventTypeNames`.

```bash theme={null}
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"]
  }'
```

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

<Warning>
  The field is `eventTypeNames` — an array of event names. Do not use `events`.
</Warning>

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

## List available event types

Fetch the catalog of subscribable events:

```bash theme={null}
curl -X GET "$BASE_URL/webhooks/event-types" \
  -H "Authorization: Basic $AUTH"
```

Update or remove a webhook with `PATCH /v1/webhooks/{wh_id}` and `DELETE /v1/webhooks/{wh_id}`.

## Handle deliveries

<Steps>
  <Step title="Verify the signature">
    Every delivery is signed. Verify the signature against your webhook secret before trusting the payload. Reject anything that fails verification.
  </Step>

  <Step title="Respond 2xx fast">
    Return a `2xx` quickly. Do the real work asynchronously — queue the event and acknowledge immediately. Slow responses count as failures.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  For local development, point the `url` at a tunnel such as [webhook.site](https://webhook.site) or [ngrok](https://ngrok.com) to inspect deliveries.
</Tip>

For the full event catalog, payload shapes, and signature scheme, see [Webhooks](/concepts/webhooks).

<Tip>
  Next → [Go live](/get-started/journey/go-live).
</Tip>