Webhook events and payloads

Use this page to quickly see which events Blaaiz emits and what every webhook payload contains.

Event types

Your business has two webhook URLs: collection_url and payout_url. The table below shows every event and which URL it is delivered to.

Event	Description	Delivered to	Guide
`collection.initiated`	Collection request created	`collection_url`	Collection
`collection.pending`	Awaiting customer payment	`collection_url`	Collection
`collection.completed`	Payment received successfully	`collection_url`	Collection
`collection.failed`	Payment failed	`collection_url`	Collection
`collection.expired`	Interac money request expired before the payer approved it	`collection_url`	Collection
`refund_initiated`	Refund of a collection to source started	`collection_url`	Refund
`refund`	Refund of a collection to source succeeded or failed (see `status`)	`collection_url`	Refund
`payout.initiated`	Payout has been created	`payout_url`	Payout
`payout.processing`	Payout is being processed	`payout_url`	Payout
`payout.completed`	Payout completed successfully	`payout_url`	Payout
`payout.failed`	Payout failed	`payout_url`	Payout
`crypto.payout.processing`	Crypto payout accepted for processing	`payout_url`	Crypto API
`crypto.payout.successful`	Crypto payout completed successfully	`payout_url`	Crypto API
`crypto.payout.failed`	Crypto payout reached a final failed state	`payout_url`	Crypto API
`crypto.deposit.successful`	Crypto deposit credited to a business crypto wallet	`collection_url`	Crypto API
`customer.status_changed`	Customer’s `verification_status` transitioned. The single event covers all customer-level transitions for both KYC (individual) and KYB (business): inspect `old_status` and `new_status` on the payload to know which way it moved. The legacy event labels `customer.verified` and `customer.rejected` are still mentioned in this guide for clarity, but the wire `event_type` value is always `customer.status_changed`.	`collection_url`	Customer
`virtual_account.created`	Virtual account created	`collection_url`	Virtual account
`virtual_account.ready`	Virtual account ready to receive funds	`collection_url`	Virtual account
`virtual_account.rejected`	Virtual account verification rejected	`collection_url`	Virtual account
`virtual_account.failed`	Virtual account creation failed	`collection_url`	Virtual account
`virtual_account.credited`	Funds received in virtual account	`collection_url`	Virtual account

Payout and crypto payout events use your payout_url. Crypto deposit events and all other events use your collection_url.

Payload structure

Fiat and collection webhook payloads include:

event — The event type
data — The event data object
timestamp — When the event occurred
signature — HMAC signature for verification (header: x-blaaiz-signature)

Always verify the x-blaaiz-signature using your webhook signing_secret to ensure the webhook originates from Blaaiz.

Crypto payout payload

Crypto payout webhooks use a flat JSON object. They do not use the data wrapper from other webhook events.

{
  "event": "crypto.payout.successful",
  "transaction_id": "crypto-transaction-id",
  "transaction_reference": "CRYPTO-REF",
  "transaction_status": "SUCCESSFUL",
  "wallet_id": "crypto-wallet-id",
  "currency": "USDC",
  "amount": "100.000000",
  "network": "ETHEREUM_MAINNET",
  "token": "USDC",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f6E123",
  "transaction_hash": "0xabc123",
  "event_id": "webhook-log-id",
  "type": "crypto.payout.successful"
}

The crypto.payout.failed event includes failure_reason. Blaaiz sends this event only for a final failed state.

Crypto deposit payload

Crypto deposit webhooks use the same flat JSON structure. Blaaiz sends the event after it credits the business crypto wallet.

{
  "event": "crypto.deposit.successful",
  "transaction_id": "crypto-transaction-id",
  "transaction_reference": "CRYPTO-REF",
  "transaction_status": "SUCCESSFUL",
  "wallet_id": "crypto-wallet-id",
  "currency": "USDC",
  "amount": "100.000000",
  "fee": "1.000000",
  "net_amount": "99.000000",
  "network": "ETHEREUM_MAINNET",
  "token": "USDC",
  "source_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f6E123",
  "transaction_hash": "0xabc123",
  "event_id": "webhook-log-id",
  "type": "crypto.deposit.successful"
}

Webhook retries

A webhook can be delivered more than once. Use event_id to process each event once in your system. Return a 2xx response when you accept a webhook. Blaaiz can retry a delivery that does not receive a 2xx response. Use the webhook log endpoints to inspect delivery status. You can replay an eligible failed delivery.

⚙️ Best practices

Reply with a 2xx promptly and process work asynchronously if needed.

Implement idempotency using the event_id so duplicate deliveries don’t double-process work.

Return non-2xx only when you truly want a retry.

Data retention

Webhook logs (payloads, responses, attempt history) are retained for 90 days. After 90 days, records are pruned for both successful and failed deliveries.

If you need webhook data beyond 90 days, store it in your own systems.
Replay is only available for webhooks within the 90-day window.

Getting Started

Core Concepts

Guides

Webhooks

Frequently asked questions

Webhook events and payloads

Event types

Payload structure

Crypto payout payload

Crypto deposit payload

Webhook retries

Data retention

​Event types

​Payload structure

​Crypto payout payload

​Crypto deposit payload

​Webhook retries

​Data retention

Event types

Payload structure

Crypto payout payload

Crypto deposit payload

Webhook retries

Data retention