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 three webhook URLs: collection_url, payout_url, and kyc_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
`auto_deposit_email.active`	Interac auto-deposit registration activated	`collection_url`, with `payout_url` fallback	Interac auto-deposit email
`auto_deposit_email.blocked`	Interac auto-deposit registration blocked or an active registration removed	`collection_url`, with `payout_url` fallback	Interac auto-deposit email
`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. The payload identifies the customer when a customer wallet address is funded.	`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
`merchant.kyc.session.completed`	A Signa verification session finished review. `data.result` is `APPROVED` or `REJECTED`	`kyc_url`	Signa
`merchant.kyc.session.expired`	A Signa verification session passed its deadline before it completed	`kyc_url`	Signa

Payout and crypto payout events use your payout_url. Signa events use your kyc_url. Interac auto-deposit registration events use collection_url, or payout_url when collection_url is null. Crypto deposit events and the other listed events use collection_url.

Signa events use their own payload shape and their own retry schedule. See Signa webhooks.

Interac auto-deposit registration events use a flat payload with type, email, status, message, and event_id. See registration status webhooks for the exact payload.

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.

The customer_id field is at the top level. The payload has no source object.

{
  "event": "crypto.deposit.successful",
  "transaction_id": "crypto-transaction-id",
  "transaction_reference": "CRYPTO-REF",
  "transaction_status": "SUCCESSFUL",
  "wallet_id": "crypto-wallet-id",
  "customer_id": "customer-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

The retry, log, and replay guidance below does not apply to Interac auto-deposit registration events. Those events use synchronous delivery without automatic retries or webhook logs. Use the read endpoints to check a missed status update.

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.