Webhooks - Bringin Partner API

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.

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.

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

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

​/verification-status

​/order-status

​/connection-status

​Handling Webhooks

/verification-status

/order-status

/connection-status

Handling Webhooks