Callbacks

A callback is an outbound HTTP webhook that B2BINPAY DeFi sends to your system when an invoice- or payout-related event occurs. When such an event happens, the app sends a POST request with a JSON body to the callback URL you configured, so you can react to payments and operations in real time.

Callback payload

Every callback body uses the same top-level structure:

id string · UUID

The unique callback identifier, in the UUID format.

type string

The callback type.

Invoice-related types:

• INVOICE_CREATED: The invoice was created.
• INVOICE_DEPOSIT_RECEIVED: An incoming deposit transaction was detected on the invoice address.
• INVOICE_DEPOSIT_CONFIRMED: The incoming transaction has reached the required number of confirmations.
• INVOICE_PAID: The paid amount is equal to the requested amount and the invoice status changes to Paid (for invoices with an indicated amount).
• INVOICE_UNRESOLVED: The paid amount is greater than the requested amount and the invoice status changes to Unresolved (for invoices with an indicated amount).
• INVOICE_CLAIMED: Funds from the invoice address have been claimed to the account multisig wallet.

Payout-related types:

• PAYOUT_CREATED: The payout was created.
• PAYOUT_SENT: The payout transaction was sent to the blockchain.
• PAYOUT_EXECUTED: The payout transaction was mined to a block and executed successfully.
• PAYOUT_CONFIRMED: The payout transaction reached the required number of confirmations.
• PAYOUT_FAILED: The payout transaction failed in the blockchain.
• PAYOUT_CANCELLED: The payout was canceled before it was executed.

operation_id string · UUID

The identifier of the original operation: invoiceId for invoice-related callback types, payoutId for payout-related callback types.

operation_type string

The original operation type: invoice or payout.

timestamp string

The date and time the callback was generated, in ISO 8601 format (UTC). Updated with each callback resend attempt.

data object

The callback-specific payload.

Always includes the original operation object (invoice or payout). May include transactions, claims, and other associated objects.

Below you can find examples of payloads for different callback types.

Callback verification

Each callback request is signed to confirm that it was sent by the B2BINPAY DeFi API and was not modified in transit.

The signature is provided in the X-CALLBACK-SIGNATURE HTTP header, that contains an HMAC-SHA256 hash of the raw JSON payload and your callback secret.

Verification steps