Skip to main content
We sends webhooks to notify you about important events related to transfers, deposits, swaps, onramps, and offramps. You can configure webhooks in your dashboard or via API to receive notifications.

​
Webhook Events

The following events are available:
EventDescription
deposit:pendingDeposit transaction has been initiated
deposit:processingDeposit transaction is being processed
deposit:completedDeposit transaction has been completed
deposit:failedDeposit transaction has failed
offramp:pendingOfframp transaction has been initiated
offramp:processingOfframp transaction is being processed
offramp:completedOfframp transaction has been completed
offramp:failedOfframp transaction has failed
swap:pendingSwap transaction has been initiated
swap:processingSwap transaction is being processed
swap:completedSwap transaction has been completed
swap:failedSwap transaction has failed
onramp:pendingOnramp transaction has been initiated
onramp:processingOnramp transaction is being processed
onramp:completedOnramp transaction has been completed
onramp:failedOnramp transaction has failed
transfer:pendingTransfer transaction has been initiated
transfer:processingTransfer transaction is being processed
transfer:completedTransfer transaction has been completed
transfer:failedTransfer transaction has failed

​
Webhook Verification

To ensure the authenticity of webhook requests, We sign each webhook with your unique webhook secret key. You should verify the signature before processing the webhook notification received. 
import crypto from 'crypto';

app.post('/your-webhook-endpoint', (req, res) => {
  const signatureFromHeader = req.header('x-webhook-signature');
  const yourWebhookSecret = process.env.YOUR_WEBHOOK_SECRET!;

  const bodyString = JSON.stringify(req.body);
  const computedSignature = crypto.createHmac('sha256', yourWebhookSecret).update(bodyString).digest('hex');

  if (!signatureFromHeader || computedSignature !== signatureFromHeader) {
    return res.status(401).send('Invalid webhook signature');
  }

  const { event, payload } = req.body;
  res.status(200).send('Webhook received successfully');
});

​
Sample Webhook

Here’s an example of webhook notification for pending transfer: 
{
  "event": "transfer:pending",
  "payload": {
    "type": "transfer",
    "sender": "0x4022006770deec7e5cAF419D23e1C0838d278979",
    "receiver": "0xd2218fa0F51D0d2c67868487603D44CB5CcCD228",
    "amount": 25000,
    "direction": "outgoing",
    "status": "pending",
    "fee": 0,
    "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "blockchain": 8453,
    "wallet": "68bb7d8399900e253084e294",
    "user": "68bb7d8399900e253084e2h8",
    "hash": "0xa0f7706295794b000e9486cde30fea39b93fdc575f3c12645148a88b5b7f0506",
    "reference": "ouq7400vadmk6obkjhuooqs044aprp",
    "asset": "base:usdc"
  },
  "timestamp": "1758641923078"
}

​
Payload Fields

FieldTypeDescription
eventstringThe event type (e.g., “transfer:pending”)
payload.typestringThe transaction type
payload.senderstringThe sender’s wallet address
payload.receiverstringThe receiver’s wallet address
payload.amountnumberThe transaction amount
payload.directionstringTransaction direction (“incoming” or “outgoing”)
payload.statusstringCurrent transaction status
payload.feenumberTransaction fee
payload.tokenstringToken contract address
payload.blockchainnumberBlockchain identifier
payload.walletstringWallet identifier
payload.userstringUser identifier
payload.hashstringTransaction hash
payload.referencestringUnique reference for the transaction
payload.assetstringAsset identifier (e.g., “base:usdc”)
timestampstringUnix timestamp of the event

​
Need Help?

Our team is here to help you succeed:
Need help? Contact our team at hello@bread.africa or Twitter.
⌘I