Real-Time Events
Via Webhooks
Receive instant notifications when events happen in your Quub account. Build reactive applications with our reliable webhook system.
How Webhooks Work
Simple 3-step process to start receiving real-time notifications
Register Endpoint
Add your webhook URL in the dashboard and select which events you want to receive.
Events Trigger
When an event occurs, we immediately send a POST request to your endpoint with the event data.
Process & Respond
Handle the event in your application and return a 200 status to acknowledge receipt.
Available Event Types
Subscribe to the events that matter to your application
Wallet Events
Transaction Events
DeFi Events
Security Events
Portfolio Events
System Events
Webhook Payload
Example webhook payload structure
{
"id": "evt_1234567890",
"type": "transaction.confirmed",
"created": 1697041234,
"data": {
"object": {
"id": "tx_9876543210",
"status": "confirmed",
"from": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
"to": "0x8f0E2A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F",
"amount": "100.00",
"currency": "USDC",
"chain": "ethereum",
"hash": "0xabc123def456...",
"confirmations": 12,
"gas_used": "21000",
"gas_price": "25",
"timestamp": 1697041200,
"metadata": {
"user_id": "user_123",
"order_id": "order_456"
}
}
},
"livemode": true,
"pending_webhooks": 1,
"request": {
"id": "req_abc123",
"idempotency_key": "key_xyz789"
}
}Implementation Guide
Code examples for handling webhooks in your application
Node.js / Express
⚡const express = require('express');
const crypto = require('crypto');
app.post('/webhooks/quub',
express.raw({type: 'application/json'}),
(req, res) => {
const signature = req.headers['x-quub-signature'];
const payload = req.body;
// Verify signature
const hash = crypto
.createHmac('sha256', webhookSecret)
.update(payload)
.digest('hex');
if (hash !== signature) {
return res.status(401).send('Invalid signature');
}
const event = JSON.parse(payload);
// Handle event
switch (event.type) {
case 'transaction.confirmed':
handleTransaction(event.data.object);
break;
case 'wallet.balance_changed':
updateBalance(event.data.object);
break;
}
res.status(200).send('Success');
});Python / Flask
🐍from flask import Flask, request
import hmac
import hashlib
@app.route('/webhooks/quub', methods=['POST'])
def webhook():
signature = request.headers.get('X-Quub-Signature')
payload = request.data
# Verify signature
expected = hmac.new(
webhook_secret.encode(),
payload,
hashlib.sha256
).hexdigest()
if signature != expected:
return 'Invalid signature', 401
event = request.json
# Handle event
if event['type'] == 'transaction.confirmed':
handle_transaction(event['data']['object'])
elif event['type'] == 'wallet.balance_changed':
update_balance(event['data']['object'])
return 'Success', 200Best Practices
Follow these guidelines for reliable webhook handling
Verify Signatures
Always verify the webhook signature using the secret key to ensure the request is from Quub.
Respond Quickly
Return a 200 status immediately. Process heavy tasks asynchronously in a queue.
Handle Retries
Make your endpoint idempotent. We retry failed webhooks up to 3 times with exponential backoff.
Log Everything
Keep logs of all received webhooks for debugging and audit purposes.
Test Thoroughly
Use our test mode to simulate events before deploying to production.
Monitor Health
Set up alerts for failed webhook deliveries in the dashboard.
Webhook Security
How we ensure webhook authenticity and security
Signature Verification
Every webhook includes an X-Quub-Signature header containing an HMAC-SHA256 signature of the payload.
signature = HMAC_SHA256(webhook_secret, payload) HTTPS Only
All webhooks are sent over HTTPS to ensure data is encrypted in transit. HTTP endpoints are not supported.
IP Allowlisting
For additional security, you can allowlist our webhook IPs:
Timestamp Validation
Each webhook includes a created timestamp. Reject events older than 5 minutes to prevent replay attacks.
if (now - event.created > 300) reject() Ready to Integrate Webhooks?
Start receiving real-time notifications for events in your Quub account. Set up your first webhook endpoint in minutes.