Blockonomics sends HTTP callbacks to your server when payments are received on your addresses. Each callback includes the following parameters:

status - Transaction status: 0 (Unconfirmed), 1 (Partially Confirmed), 2 (Confirmed)
addr - The receiving Bitcoin address
value - Payment amount in satoshis
txid - Transaction ID of the payment
rbf - Included only for unconfirmed transactions that use Replace-By-Fee (optional)

Configuration

Configure your callback URL in Dashboard > Stores. You can include a secret parameter in the URL for additional security (e.g., https://yourserver.com/callback?secret=your_secret_key).

Example Callback

When a payment is received, Blockonomics will make an HTTP GET request to your callback URL with parameters:

https://yourserver.com/callback?secret=your_secret_key&txid=abc123def456...&addr=1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa&value=50000&status=0&rbf=1

Your server should respond with HTTP status 200 to acknowledge receipt.

Callback Behavior

A callback is considered successful when your server returns HTTP status 200. Failed callbacks are automatically retried up to 7 times with exponential backoff starting at 4 seconds.

Note: Callbacks are only sent for transactions with a value greater than zero. Each unique combination of transaction, status, and address is sent only once.

Security Recommendations

Wait for confirmations: Always wait for at least one confirmation before delivering products or services.

Zero-confirmation risk: If you need to accept unconfirmed transactions for instant delivery of digital goods, reject any transaction that includes the rbf attribute. RBF (Replace-By-Fee) transactions can be cancelled or replaced by the sender before confirmation, creating a risk of payment reversal.

What’s Next

What’s Next