# Callbacks

> Receive real-time payment notifications via HTTP callbacks when a payment status changes.

Source: https://developers.blockonomics.co/docs/guides/callbacks
Last updated: 2026-07-28

## Overview

When a payment is sent to an address generated by Blockonomics, our system sends an HTTP GET request to your configured callback URL. This lets you fulfill orders and update payment state without polling the API.

## Setting Up a Callback URL

In your Blockonomics dashboard, configure a callback URL for each store:

```
https://yoursite.com/api/payment-callback?secret=RANDOM_SECRET
```

Include a secret query parameter — you'll use it to verify the callback is genuine.

## Callback Payload

Blockonomics sends a `GET` request (not POST) to your callback URL with these query parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `addr` | string | The address that received payment |
| `crypto` | string | The cryptocurrency used. Absent (or `BTC`) for Bitcoin, `USDT` for USDT callbacks |
| `status` | integer | Confirmation status (see below) |
| `value` | integer | Amount received, in satoshis for BTC or base units (6 decimal places) for USDT |
| `txid` | string | Transaction ID on the blockchain |
| `rbf` | integer | Only present on unconfirmed transactions using Replace-By-Fee (see security notes below) |

### Status Values

| Value | Meaning |
|-------|---------|
| `0`   | Unconfirmed (in mempool) |
| `1`   | 1 confirmation |
| `2`   | 2+ confirmations (final) |

For most e-commerce use cases, treat **status ≥ 2** as a confirmed payment.

## Example Callback

```
GET https://yoursite.com/api/payment-callback?secret=RANDOM_SECRET&addr=1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa&status=2&value=500000&txid=c4978bfc9b4cd632fb37eb5f69c7c686ae364d9cb1b32ec01c0f8bae72530a4e
```

## Handling the Callback

```javascript
// Express.js example
app.get('/api/payment-callback', (req, res) => {
  const { secret, addr, status, value, txid } = req.query

  // Verify the secret
  if (secret !== process.env.BLOCKONOMICS_CALLBACK_SECRET) {
    return res.status(403).send('Forbidden')
  }

  // Only act on confirmed payments
  if (parseInt(status) >= 2) {
    const btcAmount = parseInt(value) / 1e8
    // Fulfill the order associated with `addr`
    fulfillOrder(addr, btcAmount, txid)
  }

  res.send('OK')
})
```

## Callback Behavior

- A callback is **successful** when your server returns HTTP `200`
- Failed callbacks are retried up to **7 times** with exponential backoff starting at 4 seconds
- Callbacks are only sent for transactions with a **value greater than zero**
- Each unique combination of `txid`, `status`, and `addr` is sent **only once**

## Best Practices

- **Always verify the secret** before processing any callback
- **Be idempotent** — the same callback may arrive multiple times with increasing `status`
- **Respond quickly** — return `200 OK` immediately, do heavy work in the background
- **Wait for confirmations** — always wait for `status >= 2` before delivering products or services
- **Watch for RBF** — if you need to accept unconfirmed transactions (`status = 0`), reject any callback that includes the `rbf` parameter. RBF transactions can be cancelled or replaced by the sender before confirmation