Webhooks

Breet sends webhook notifications to your server whenever important events occur, such as incoming crypto deposits or withdrawal status changes. Your application can listen for these events and respond accordingly.

Outgoing delivery logs & manual resend: To list stored deliveries, view attempt history for one event, or trigger a one-off resend by trade/withdrawal reference, use the Webhooks group in the API reference tab (endpoints under /transactions/webhooks). This guide covers incoming payloads and verification on your server.

Crypto wallet deposit webhooks

These webhooks fire whenever a wallet address receives crypto assets. You will receive events for the following transaction states:

Event	Description
`trade.pending`	An incoming crypto transaction has been detected on the blockchain but has not yet been fully confirmed or processed.
`trade.completed`	The transaction is fully confirmed, has passed all checks, and your account has been credited.
`trade.flagged`	The transaction is confirmed on-chain but below the asset’s minimum deposit amount. Funds are held and not credited. Resolve it with a top-up, a resolution fee, or auto-resolution — see how flagged deposits are resolved.
`trade.deleted`	The transaction failed on-chain — it was rejected, cancelled, or blocked before it could confirm. Nothing is credited and the deposit is terminal.

Payload example

{
  "id": "692f91aa729255932afe9078",
  "asset": "SOL_TEST",
  "feePercentage": 1.5,
  "feeAmountInUsd": 0.32,
  "rate": 1600,
  "conversionRate": 1
  "cryptoAmount": 0.00025406,
  "amountInUSD": 21.379427842514175,
  "flagFeeUSD": 0,
  "vaultId": "121",
  "senderAddress": "bc1qf43tdrym26qlz8rg06f88wg35n27uhcf29zs4f",
  "destinationAddress": "6DKYpZfd86BUDTjPe4E3JEGwnYW99KU3NDazk7BjpN8V",
  "destinationDescription": "Partner_testingizzy",
  "txHash": "aa801188ukdjfhdbf3771dfdf86388b8b694a2ac0226748346y34kbc3",
  "status": "completed",
  "confirmations": 3,
  "note": "",
  "isWrongAssetDeposit": true,
  "event": "trade.completed",
  "eventId": "e3f2a9c4-71bd-4a08-9f3e-5c2d81b0a417",
  "eventTime": "2025-12-01T18:44:15.493Z",
  "createdAt": 1764614655493,
  "updatedAt": 1764616198265,
  "index": 19,
  "blockInfo": {
    "blockHeight": "926040",
    "blockHash": "0000000000000000000158f293cda641e08a144673dc03814b187e8db758c929"
  }
}

Payload fields

Field	Type	Description
`id`	string	Unique identifier for the transaction.
`asset`	string	The crypto asset involved (e.g., `ETH`, `BTC`).
`feePercentage`	number	Breet’s platform fee rate applied to the trade, expressed as a percentage (e.g., `0.5` means 0.5%).
`feeAmountInUsd`	number	The platform fee amount in USD, calculated as `(feePercentage / 100) x amountInUSD`.
`cryptoAmount`	number	Amount of crypto transferred.
`amountInUSD`	number	Value of the transaction in USD.
`flagFeeUSD`	number	Fee applied for trades below minimum asset requirement. Initially `0`. Populated on the `trade.completed` event when a flagged deposit is released by paying the resolution fee.
`vaultId`	string	ID of the vault handling the transaction.
`rate`	number	The NGN per USD rate.
`conversionRate`	number	The NGN to GHS rate applied for GHS transactions, always `1` for NGN.
`senderAddress`	string	Wallet address of the sender.
`destinationAddress`	string	Wallet address receiving the funds.
`destinationDescription`	string	Optional description for the recipient.
`txHash`	string	Blockchain transaction hash.
`status`	string	Transaction status (`pending`, `completed`, `flagged`, `deleted`).
`confirmations`	number	Number of blockchain confirmations.
`note`	string	Optional note associated with the transaction.
`isWrongAssetDeposit`	boolean	Present and set to `true` only on the `trade.pending` event when this deposit was recovered from a wrong-asset send (e.g. ETH sent to a USDT address). Omitted from all other payloads. See Wrong asset.
`balanceRemaining`	number	Present only on the `trade.flagged` event. How much more, in USD, has to land on the same address in the same asset before the deposit clears the minimum and is credited. It already accounts for every outstanding flagged deposit at that address, so show this figure to your customer as the amount to top up. `0` on a deposit flagged by an AML check, which a top-up cannot resolve.
`event`	string	Webhook event type (`trade.completed`, `trade.pending`, `trade.flagged`, `trade.deleted`).
`eventId`	string	Opaque identifier for this event. Identical across every retry and resend of it, so it is the key to deduplicate on. See Ordering and duplicates.
`eventTime`	string (ISO 8601)	When this event occurred. Fixed when the event is created and identical across every retry, so it orders events for the same `id`. See Ordering and duplicates.
`createdAt`	timestamp	Transaction creation timestamp (milliseconds).
`updatedAt`	timestamp	Last update timestamp (milliseconds).
`index`	number	Internal index for ordering transactions.
`blockInfo.blockHeight`	string	Block height in the blockchain.
`blockInfo.blockHash`	string	Hash of the block containing this transaction.

Auto-settlement fields

When a bank account is linked to a wallet address and auto-settlement is enabled, the webhook payload includes additional fields. For a full explanation of how auto-settlement works, see the Auto-settlement guide.

Field	Type	Description
`markupPercent`	number	The percentage markup configured on your integration (e.g. `2.5`, optionally set by you).
`markupAmount`	number	The absolute amount deducted as markup from the converted local currency amount.
`amountSettled`	number	The final amount paid out to the linked bank account, after markup deduction.

If a markup percentage is set, it is deducted from the transaction amount before the final payout is calculated. For example, if a trade amount is 1,000 USD and a 5% markup is applied, 50 USD is deducted and the settlement is calculated based on 950 USD.

Behavior notes

The webhook may send multiple events for the same transaction as its status changes. For example, a transaction may first trigger trade.pending, then later trade.completed. Use eventTime to order them — see Ordering and duplicates.
The confirmations field indicates how many blockchain confirmations the transaction has received. This is especially important for trade.completed events.
trade.deleted is terminal: nothing is credited and no trade.completed follows for that id. A deposit that fails this way may have already sent you a trade.pending.

trade.flagged adds balanceRemaining to the payload above — the USD still needed on that address to clear the minimum:

{
  "id": "692f91aa729255932afe9078",
  "asset": "SOL_TEST",
  "amountInUSD": 3,
  "flagFeeUSD": 0,
  "balanceRemaining": 7,
  "status": "flagged",
  "event": "trade.flagged",
  "eventId": "e3f2a9c4-71bd-4a08-9f3e-5c2d81b0a417",
  "eventTime": "2025-12-01T18:44:15.493Z"
}

For auto-settlement trades, withdrawal events are also sent and the related trade ID is included in the notification response.

Address creation webhook

This webhook fires as a fallback when a wallet address is successfully generated. It confirms the address is live and ready to receive deposits.

Event	Description
`trade.address.created`	A wallet address has been generated and is ready to receive deposits. Sent as a fallback alongside the API response.

Payload example

{
  "event": "trade.address.created",
  "eventId": "8b4c7d21-0e96-4f3a-b58d-1a7c6e93f042",
  "eventTime": "2026-01-15T13:35:15.967Z",
  "id": "6a1e1281ab08f50ad3127259",
  "address": "TB3yDFJXFKM2BySqhCPgyRuSzVkSR2CVam",
  "asset": "TRX_TEST",
  "label": "user-12345"
}

Payload fields

Field	Type	Description
`event`	string	Always `trade.address.created`.
`eventId`	string	Opaque identifier for this event. Identical across every retry and resend of it, so it is the key to deduplicate on. See Ordering and duplicates.
`eventTime`	string (ISO 8601)	When this event occurred. Fixed when the event is created and identical across every retry.
`id`	string	Unique identifier for the generated address record.
`address`	string	The wallet address that was created.
`asset`	string	The asset identifier the address was generated for (e.g., `TRX_TEST`).
`label`	string	Unique name or ID for the bearer of this wallet address. Preferably the user ID or username.

Fiat/Crypto withdrawal webhooks

These webhooks fire whenever a withdrawal is created or when its status changes.

Event	Description
`withdrawal.pending`	The withdrawal request has been received and is being processed.
`withdrawal.processing`	The withdrawal has been approved and is being paid out. Not yet confirmed.
`withdrawal.completed`	The withdrawal has been successfully processed and paid out.
`withdrawal.reversed`	The payout was attempted but came back as a failure. Funds are refunded to your wallet.
`withdrawal.rejected`	The withdrawal was rejected during internal review, before any payout was attempted. Funds are refunded to your wallet.

Payload example

{
  "id": "6968ed1398fea49e805363bb",
  "event": "withdrawal.pending",
  "eventId": "2d7f0b54-9c31-4e6a-8f27-b3e5a0c41d89",
  "eventTime": "2026-01-15T13:35:15.967Z",
  "amount": 1000,
  "originalAmount": 1000,
  "currency": "usd",
  "status": "pending",
  "txHash": "0x123abcdef",
  "reference": "6968ed1398fea49e805363bb",
  "fee": 10,
  "meta": {
    "walletAddress": "14grJpemFaf88c8tiVb77W7TYg2W3ir6pfkKz3YjhhZ5",
    "network": "SOL",
    "token": "USDT",
    "symbol": "USDT",
    "avatar": "https://assets.breet.io/token-network-assets/USDT_SOL.png",
    "label": "",
    "txLink": "https://solscan.io/tx/"
  },
  "reason": "",
  "createdAt": "2026-01-15T13:35:15.967Z",
  "updatedAt": "2026-01-15T13:35:15.967Z"
}

Payload fields

Field	Type	Description
`id`	string	Unique identifier for the withdrawal request.
`event`	string	Webhook event type (`withdrawal.pending`, `withdrawal.processing`, `withdrawal.completed`, `withdrawal.reversed`, `withdrawal.rejected`).
`eventId`	string	Opaque identifier for this event. Identical across every retry and resend of it, so it is the key to deduplicate on. See Ordering and duplicates.
`eventTime`	string (ISO 8601)	When this event occurred. Fixed when the event is created and identical across every retry, so it orders events for the same `id`. See Ordering and duplicates.
`txHash`	string	Blockchain transaction hash (only present on completed transactions).
`amount`	number	Total debited from your balance. Equals `originalAmount`, plus the fee when your fee bearer is `business`.
`originalAmount`	number	The amount you requested, before any fee handling.
`payoutAmount`	number	What the destination receives, in the withdrawal currency. Equals `originalAmount − fee` with the `user` bearer, or `originalAmount` with `business`.
`currency`	string	Currency of the withdrawal (e.g., `usd`).
`status`	string	Current withdrawal status (`pending`, `processing`, `completed`, `reversed`, `rejected`).
`reference`	string	Unique reference for the withdrawal. Always the same value as `id`. We recommend using `id` instead.
`externalId`	string	Your own reference, if you sent one on the request.
`trade`	string	Trade ID (if withdrawal was initiated from a trade).
`fee`	number	Fee charged for processing the withdrawal, in the withdrawal currency.
`cryptoAmount`	number	Crypto units sent on-chain, after the fee. Crypto withdrawals only.
`feeCrypto`	number	The same fee, in crypto units. Crypto withdrawals only.
`meta`	object	Additional metadata related to the withdrawal destination.
`meta.type`	string	Withdrawal destination type. `address` for crypto withdrawals, or the bank account type (e.g. `nuban`) for bank withdrawals.
`meta.bankId`	string	Bank identifier for NUBAN withdrawals.
`meta.bankName`	string	Name of the destination bank.
`meta.accountName`	string	Verified bank account holder name.
`meta.account`	string	Internal account reference ID.
`meta.accountNumber`	string	Bank account number (NUBAN).
`meta.autoSettlement`	boolean	Whether the withdrawal is processed automatically.
`meta.narration`	string	Transfer narration or description shown on bank statement.
`meta.fee`	number	Withdrawal fee charged for the transaction. Bank withdrawals only — on crypto withdrawals read the top-level `fee`.
`meta.feeBearer`	string	Who absorbed the withdrawal fee — `user` (deducted from the payout) or `business` (added to the amount debited from your balance). Set on every partner withdrawal, bank and crypto. See Who bears the fee.
`meta.walletAddress`	string	Destination wallet address for crypto withdrawals.
`meta.network`	string	Blockchain network used for the withdrawal (e.g., `SOL`).
`meta.token`	string	Token being withdrawn (e.g., `USDT`).
`meta.symbol`	string	Token symbol.
`meta.avatar`	string	URL to the token or network asset icon.
`meta.label`	string	Optional label or description for the withdrawal destination.
`meta.txLink`	string	Base URL for viewing the transaction on a blockchain explorer.
`meta.assetId`	string	Breet’s asset identifier for the token and chain.
`meta.cryptoAmountRate`	number	USD per crypto unit used for the conversion. Crypto withdrawals only.
`meta.cryptoAmount`	number	The crypto amount you requested, before the fee. Present when you priced the request in crypto units.
`meta.amountUsd`	number	The USD amount you requested, before the fee. Present when you priced the request in USD.
`reason`	string	Reason for rejection or reversal (empty if not applicable).
`createdAt`	string (ISO 8601)	Timestamp when the withdrawal was created.
`updatedAt`	string (ISO 8601)	Timestamp of the most recent status update.

Behavior notes

A single withdrawal may trigger multiple webhook events as its status progresses.
withdrawal.pending is always sent first.
txHash will not be present until the withdrawal is completed.
Always rely on the event and status fields to determine the current state of a withdrawal.
Events may arrive out of order after a failed delivery is retried — see Ordering and duplicates.

Ordering and duplicates

Breet delivers each event at least once, and delivery is not ordered. A failed delivery is retried on its own schedule while newer events for the same trade or withdrawal keep flowing, so a retried trade.pending can reach you after the trade.completed for the same trade. Every payload carries two fields for this:

eventId — an opaque identifier for the event. It is derived from the event’s identity, so every retry and every manual resend of the same event carries the same eventId.
eventTime — the moment the state actually changed, in ISO 8601.

Both are fixed when the event is created, not when it is delivered. The whole payload is captured at that same moment, so a retry or a resend carries exactly the values the state had when the event occurred — never the values the trade or withdrawal has now. To process events safely:

Deduplicate on eventId. It identifies one event. Receiving it twice means a retry or a resend, not a new state change. (id + event identifies the same thing if you already key on that pair.)
Keep the last applied eventTime per id. Discard any event whose eventTime is older than or equal to the one you last applied for that id.
Never move a terminal state backwards. Once a trade is completed or a withdrawal is completed, rejected, or reversed, ignore any later-arriving pending or processing event for it.

Always return a 2xx as soon as you have stored the event. Returning a non-2xx triggers the retry schedule below, which is what causes out-of-order arrivals.

Webhook verification

To ensure the security and authenticity of incoming webhook notifications, Breet provides multiple layers of verification.

IP whitelisting

All webhook requests originate from Breet’s secure servers. Verify that incoming requests come from one of the following IP addresses:

101.201.155
101.225.109
101.225.97
101.225.251
89.20.62

Requests from any other IP addresses should be considered untrusted and ignored.

Webhook secret

Each webhook endpoint is configured with a webhook secret, visible in your dashboard (Go to Settings → For Developer) under the Webhook Verification Secret Key. The secret is included in every webhook request as a header:

x-webhook-secret: <your-webhook-secret>

To verify a webhook request:

Retrieve the x-webhook-secret header from the incoming request.
Compare it against the secret configured in your dashboard.
Only process the request if the secrets match.

Keep your webhook secret secure. Do not expose it in public repositories, client-side code, or logs.

Recommended verification flow

Check the request IP against the allowed Breet IPs.
Validate the x-webhook-secret header against the configured secret.
Only process the payload if both checks pass.
As an extra check, call Fetch Transaction by ID or Fetch Withdrawal by ID to confirm the transaction exists on Breet before taking any action.

Webhook retries

If your server does not respond with a successful 2xx status code, Breet automatically retries delivering the webhook using an exponential backoff schedule. Each delay is measured from the end of the previous attempt:

Attempt	Wait after previous attempt
1st retry	1 minute
2nd retry	5 minutes
3rd retry	1 hour
4th retry	4 hours
5th retry	8 hours
6th retry	12 hours

Breet makes 7 delivery attempts in total: the initial delivery plus 6 retries, spanning roughly 25 hours. Times exclude your endpoint’s own response time. After the final retry, the webhook attempt is marked as permanently failed.

Retry conditions

Retries occur when:

Your webhook endpoint returns any non-2xx HTTP status code (including 3xx, 4xx, or 5xx).
Your webhook endpoint times out.
Your server is unreachable.

Breet does not retry events where your server returns 2xx, even if the response body contains an error.

Best practices

Return a 2xx status code as soon as your server receives and accepts the webhook.
Handle duplicate deliveries. Breet may deliver the same event more than once during retries. Use eventId to detect duplicates and ensure your processing logic is idempotent.
Handle out-of-order deliveries. A retried event can arrive after a newer one for the same trade or withdrawal. Use eventTime to discard stale updates — see Ordering and duplicates.
Log all received events and failures to aid debugging.

Resending webhooks

If your server missed a webhook or you need to replay events for debugging, Breet lets you inspect delivery history and trigger manual resends. All outgoing webhook events are persisted for 7 days. You can resend webhooks in two ways:

From the dashboard — Go to Settings → For Developer → Webhook Logs to view all outgoing events, inspect delivery statuses, and resend any event with a single click.
Via the API — Use the endpoints below to programmatically list, inspect, and resend webhook events.

The API endpoints below require an active integration with API access (VIP partners). For full request/response schemas, see List outgoing webhook events, Get a single webhook event, and Resend all webhooks for a reference.

List delivery history

Retrieve a paginated list of all outgoing webhook events sent to your endpoint.

GET /transactions/webhooks

You can filter results using optional query parameters:

Parameter	Type	Description
`page`	number	Page number for pagination.
`reference`	string	Filter by a specific trade or withdrawal ID.
`status`	string	Filter by delivery outcome: `delivered` or `failed`.
`eventName`	string	Filter by event type (e.g., `trade.completed`, `withdrawal.pending`).

View a single event

Fetch full details for a specific webhook event, including every delivery attempt with timestamps and HTTP status codes.

GET /transactions/webhooks/{id}

The response includes the attempts array, which records each delivery try with the response status code and timestamp — useful for diagnosing endpoint failures.

Resend by reference

Trigger an immediate redelivery of all webhook events associated with a given trade or withdrawal reference.

POST /transactions/webhooks/resend/{reference}

The reference is the trade or withdrawal document ID (the same value as id in your webhook payloads). The response returns the result of each resend attempt:

{
  "success": true,
  "message": "webhook resend attempted",
  "data": [
    {
      "id": "67a1b2c3d4e5f67890123456",
      "status": "delivered"
    },
    {
      "id": "67a1b2c3d4e5f67890123457",
      "status": "failed",
      "error": "webhook delivery failed"
    }
  ]
}

When to resend

Your server was down during the original delivery and all automatic retries have been exhausted.
You deployed a bug fix and need to replay events that previously failed processing.
You want to verify your webhook handler is working correctly in a staging environment.

Resent webhooks contain the same payload as the original event, including its original eventId and eventTime. Make sure your processing logic is idempotent — use eventId to detect duplicates and avoid processing the same event twice.

Getting started

Core concepts

Use cases

Crypto wallet deposit webhooks

Payload example

Payload fields

Auto-settlement fields

Behavior notes

Address creation webhook

Payload example

Payload fields

Fiat/Crypto withdrawal webhooks

Payload example

Payload fields

Behavior notes

Ordering and duplicates

Webhook verification

IP whitelisting

Webhook secret

Recommended verification flow

Webhook retries

Retry conditions

Best practices

Resending webhooks

List delivery history

View a single event

Resend by reference

When to resend

​Crypto wallet deposit webhooks

​Payload example

​Payload fields

​Auto-settlement fields

​Behavior notes

​Address creation webhook

​Payload example

​Payload fields

​Fiat/Crypto withdrawal webhooks

​Payload example

​Payload fields

​Behavior notes

​Ordering and duplicates

​Webhook verification

​IP whitelisting

​Webhook secret

​Recommended verification flow

​Webhook retries

​Retry conditions

​Best practices

​Resending webhooks

​List delivery history

​View a single event

​Resend by reference

​When to resend

Crypto wallet deposit webhooks

Payload example

Payload fields

Auto-settlement fields

Behavior notes

Address creation webhook

Payload example

Payload fields

Fiat/Crypto withdrawal webhooks

Payload example

Payload fields

Behavior notes

Ordering and duplicates

Webhook verification

IP whitelisting

Webhook secret

Recommended verification flow

Webhook retries

Retry conditions

Best practices

Resending webhooks

List delivery history

View a single event

Resend by reference

When to resend