Checkout Deposits Webhook

View as Markdown

Real-time webhook notifications sent when deposits are completed via BlockBee's hosted deposit solution. These webhooks notify you when a customer has successfully made a deposit to your deposit link and you should credit their account.

Method: You choose when creating the deposit link:

  • GET (default) - Webhook data sent as URL query parameters
  • POST (set post=1) - Webhook data sent in request body

Content-Type: You choose when creating the deposit link:

  • application/x-www-form-urlencoded (default) - Standard form encoding
  • application/json (set json=1) - JSON format in request body

Webhook Overview

Unlike custom payment flow webhooks, checkout deposit webhooks are sent only once when the deposit is complete and confirmed. There are no separate pending and confirmed states - you receive a single notification when the deposit is ready to be processed.

The webhook contains all the information you need to:

  • Verify the deposit was legitimate
  • Credit the customer's account
  • Store transaction details for your records
  • Track which user made the deposit (via custom parameters in notify_url)

Webhook Fields

uuidstring•Required

Unique identifier for each deposit made by your clients. This can be used to track any duplicate webhooks sent, in case our system doesn't mark the webhook as successful.

Important: You can use this unique identifier for idempotency to prevent processing duplicate webhooks. Store this UUID when processing deposits and check if it has already been processed.

Example: afe11bea-768b-47ae-ba0f-907379fbe5ef

txidstring•Required

Transaction hash of your client's deposit.

Example: 0xa7551df44e487f9c0507d68d90193cde2604dfcefdc975bae54535a2e0f80b32

addressstring•Required

Address generated by BlockBee where your client's deposit was received.

Example: 3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM

payment_urlstring•Required

Deposit link where the deposit came from.

Note: Any query parameters you add to the notify_url (like ?user_id=12345) will be included in the webhook payload, allowing you to track which user the deposit belongs to.

Example: https://pay.blockbee.io/deposit/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N

currencystring•Required

FIAT currency. Should be the same that you set in your Payment Settings at BlockBee's Dashboard.

Example: usd

received_amountstring•Required

Value forwarded to you, after fees deducted.

Note: The cryptocurrency/token used to make the payment is described in the parameter paid_coin.

Example: 9.24

received_amount_fiatstring•Required

Value forwarded to you, after fees deducted in the FIAT currency selected.

Note: FIAT currency. Should be the same that you set in your Payment Settings at BlockBee's Dashboard.

Example: 9.24 (represents $9.24)

exchange_ratenumber•Required

Exchange rate at the time of the payment.

Example: 20000

typestring•Required

Type of the IPN.

Example: deposit

statusstring•Required

Status of the transaction.

Example: done

Security: Verify Webhook Signatures

Reliability and Best Practices

For important information on how BlockBee handles webhook delivery, retries, and timeouts, along with essential best practices for building a reliable webhook handler, please see our main guide.

➡️ Read the How Webhooks Overview

Implementation Examples

// Express.js webhook handler
app.post('/webhook', express.json(), (req, res) => {
  // 1. Verify the webhook signature
  if (!verifyWebhookSignature(req)) {
    return res.status(401).send('Unauthorized');
  }

  // 2. Extract data from the payload
  const { 
    uuid, 
    paid_amount_fiat, 
    paid_coin, 
    txid, 
    status,
    payment_url 
  } = req.body;

  // 3. Check for duplicates using UUID
  if (isWebhookAlreadyProcessed(uuid)) {
    return res.status(200).send('*ok*');
  }

  // 4. Verify the deposit is complete
  if (status !== 'done') {
    return res.status(200).send('*ok*');
  }

  // 5. Extract user ID from payment URL (if you added custom parameters)
  const urlParams = new URLSearchParams(payment_url.split('?')[1]);
  const userId = urlParams.get('user_id');

  // 6. Process the successful deposit
  // Credit user account, store transaction, etc.
  processSuccessfulDeposit({
    userId,
    amount: paid_amount_fiat,
    coin: paid_coin,
    txid: txid,
    uuid: uuid
  });

  // 7. Mark this webhook as processed using the UUID
  markWebhookAsProcessed(uuid);

  // Always respond to stop retries
  res.status(200).send('*ok*');
});

Key Security Checks

  1. Verify Webhook Signature - Ensure the request is from BlockBee
  2. Check Deposit Status - Only process when status=done
  3. Validate UUID - Use the UUID for idempotency to prevent duplicate processing
  4. Extract User ID - Use the payment_url to get your user identifier (if you added custom parameters)

Best Practices

  • Idempotency: Use the uuid to ensure you only process each deposit once
  • Respond Quickly: Always respond with *ok* and a 200 status code
  • Asynchronous Processing: Handle long-running tasks in background jobs
  • Error Handling: Log errors but don't fail the webhook response
  • Validation: Verify all critical fields before processing the deposit