Webhooks

Traxvo sends webhooks to notify you of payment events in real-time.

Webhook URL

Set your webhook URL in two ways:

Default webhook - Configure in the Equidity Cloud dashboard
Per-address webhook - Pass callback_url when creating an address

Webhook Events

Traxvo sends two webhook events:

Event	Description
`deposit.received`	Deposit has been swept to the gas pool (Phase 1 complete)
`deposit.failed`	Deposit processing failed

deposit.received

Sent when the deposit has been swept from the deposit address to the gas pool. At this point, the funds are secured and will be forwarded to your wallet.

{
  "event": "deposit.received",
  "transaction_id": "tx_abc123def456",
  "address": "TXabc123def456ghi789jkl012mno345pqr678",
  "chain": "TRON",
  "token": "USDT",
  "amount": 100,
  "amount_usd": 100,
  "fee": 5,
  "net_amount": 95,
  "tx_hash": "abc123def456ghi789...",
  "sweep_tx_hash": "def456ghi789jkl012...",
  "status": "SWEEPING",
  "metadata": {
    "order_id": "ORD-12345",
    "customer_id": "CUST-789"
  },
  "timestamp": "2024-01-15T11:30:00.000Z"
}

deposit.failed

Sent when deposit processing fails:

{
  "event": "deposit.failed",
  "transaction_id": "tx_abc123def456",
  "address": "TXabc123def456ghi789jkl012mno345pqr678",
  "chain": "TRON",
  "token": "USDT",
  "amount": 100,
  "amount_usd": 100,
  "fee": 5,
  "net_amount": 95,
  "tx_hash": "abc123def456ghi789...",
  "sweep_tx_hash": null,
  "status": "FAILED",
  "metadata": {
    "order_id": "ORD-12345"
  },
  "timestamp": "2024-01-15T11:35:00.000Z"
}

Webhook Payload Fields

Field	Type	Description
`event`	string	Event type: `deposit.received` or `deposit.failed`
`transaction_id`	string	Unique transaction identifier
`address`	string	Deposit address that received the payment
`chain`	string	Blockchain network (TRON, BSC)
`token`	string	Token type (USDT, USDC)
`amount`	number	Deposit amount received
`amount_usd`	number	Amount in USD
`fee`	number	Fee charged
`net_amount`	number	Amount after fees (amount - fee)
`tx_hash`	string	Original deposit transaction hash
`sweep_tx_hash`	string	Sweep transaction hash (null if not swept)
`status`	string	Transaction status
`metadata`	object	Custom metadata passed when creating address
`timestamp`	string	Event timestamp (ISO 8601)

Webhook Signature

All webhooks include a signature header for verification:

X-Traxvo-Signature: sha256=abc123def456...

Verifying Signatures (JavaScript)

import crypto from 'crypto';
 
function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
 
  return `sha256=${expected}` === signature;
}
 
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-traxvo-signature'];
  const payload = req.body.toString();
 
  if (!verifyWebhook(payload, signature, process.env.TRAXVO_API_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
 
  const event = JSON.parse(payload);
 
  if (event.event === 'deposit.received') {
    // Payment received - fulfill the order
    console.log(`Received ${event.net_amount} ${event.token}`);
    console.log(`Order: ${event.metadata?.order_id}`);
  } else if (event.event === 'deposit.failed') {
    // Payment failed - notify customer
    console.log(`Payment failed for order ${event.metadata?.order_id}`);
  }
 
  res.status(200).send('OK');
});

Verifying Signatures (Python)

import hmac
import hashlib
 
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
 
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Traxvo-Signature')
    payload = request.get_data()
 
    if not verify_webhook(payload, signature, os.environ['TRAXVO_API_SECRET']):
        return 'Invalid signature', 401
 
    event = request.get_json()
 
    if event['event'] == 'deposit.received':
        print(f"Received {event['net_amount']} {event['token']}")
 
    return 'OK', 200

Retry Policy

Traxvo retries failed webhooks with exponential backoff:

Attempt	Delay
1	Immediate
2	5 seconds
3	5 seconds
4	5 seconds
5	5 seconds

After 5 failed attempts, the webhook is marked as failed and no further retries occur.

Best Practices

Return 200 quickly - Process webhooks asynchronously if needed
Verify signatures - Always validate the X-Traxvo-Signature header
Handle duplicates - Use transaction_id to deduplicate events
Use metadata - Pass order/customer IDs to correlate payments

Testing Webhooks

Use webhook.site or ngrok to test webhooks locally:

# Create address with test webhook URL
curl -X POST "https://api.traxvo.com/v1/tron/usdt/create" \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://webhook.site/your-unique-url",
    "expected_amount": 10
  }'

Webhooks

On this page