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

# Webhooks

> Receive api-keys, order updates, and connection status

Webhooks fire to the `callback` URL you provided in `POST /application/connect`. Bringin appends the event path to your URL.

**Example:** If your callback is `https://yourapp.com/bringin-webhooks`, you'll receive:

* `https://yourapp.com/bringin-webhooks/verification-status`
* `https://yourapp.com/bringin-webhooks/order-status`
* `https://yourapp.com/bringin-webhooks/connection-status`

***

## /verification-status

Fires when a user completes KYC or confirms connection to your app. **This is how you get the per-user api-key.**

```json theme={null}
POST {callback}/verification-status

{
  "userId": "f5cbb00c-d36b-4b0d-b8ef-f412757603df",
  "apikey": "MDU4MTJlNjdkYWU1NGJiZGE0ZjAxNzQ4YzM0NWJlYmE=",
  "verificationStatus": "APPROVED",
  "ref": "your-internal-user-id"
}
```

Store the `apikey` — this is the per-user key you'll use for all user-level API calls.

***

## /order-status

Fires on `SUCCESSFUL` and `FAILED` order status changes.

```json theme={null}
POST {callback}/order-status

{
  "orderId": "3521154c-...",
  "status": "SUCCESSFUL",
  "userId": "f5cbb00c-...",
  "sourceId": "tx-abc-123",
  "sourceAmount": "100000",
  "sourceCurrency": "USDC",
  "destinationAmount": "90180",
  "destinationCurrency": "EUR",
  "price": {
    "price": "0.9018",
    "currency": "EUR"
  },
  "timestamp": "2024-01-18T14:02:59.709Z"
}
```

| Field               | Description                        |
| ------------------- | ---------------------------------- |
| `orderId`           | Bringin transaction ID             |
| `status`            | `SUCCESSFUL` or `FAILED`           |
| `sourceId`          | Your reference ID (if you set one) |
| `sourceAmount`      | Amount sent (in smallest unit)     |
| `destinationAmount` | Amount received (EUR in cents)     |

***

## /connection-status

Fires when a connection becomes active (after user confirms SMS OTP).

```json theme={null}
POST {callback}/connection-status

{
  "bringinLinkId": "550e8400-...",
  "direction": "FIAT_TO_CRYPTO",
  "status": "active",
  "depositIban": "LT61 3250 0467 2289 5172",
  "ref": "your-internal-user-id"
}
```

| Field            | Present when                                   |
| ---------------- | ---------------------------------------------- |
| `depositIban`    | Buy connections (FIAT\_TO\_CRYPTO)             |
| `depositAddress` | Sell connections (CRYPTO\_TO\_FIAT, on-chain)  |
| `lnAddress`      | Sell connections (CRYPTO\_TO\_FIAT, Lightning) |

***

## Handling Webhooks

* Respond with `200` quickly — process async if needed
* You may receive the same webhook more than once — use `orderId` or `bringinLinkId` as an idempotency key
* If you didn't provide a `callback`, no webhooks are sent — use polling instead