Respond Quickly
Return a 2xx status code as fast as possible (ideally within 1-2 seconds). Process the event payload asynchronously — for example, by adding it to a message queue.
// Good - acknowledge immediately, process later
app.post('/webhooks', (req, res) => {
res.status(200).send('OK');
queue.push(req.body); // Process asynchronously
});
// Bad - processing blocks the response
app.post('/webhooks', async (req, res) => {
await processOrder(req.body); // This might take 10+ seconds
await updateDatabase(req.body);
await sendNotification(req.body);
res.status(200).send('OK');
});
Always Verify Signatures
Never trust a webhook payload without verifying the signature. See the Security guide for implementation examples in Node.js, Python, and Go.
Handle Duplicates
In rare cases, the same event may be delivered more than once (e.g., due to network issues or retries). Use the X-BitByBit-Webhook-Id header to deduplicate:
const processedEvents = new Set();
app.post('/webhooks', (req, res) => {
const eventId = req.headers['x-bitbybit-webhook-id'];
if (processedEvents.has(eventId)) {
return res.status(200).send('Already processed');
}
processedEvents.add(eventId);
// Process the event...
res.status(200).send('OK');
});
For production use, store processed event IDs in a database or Redis with a TTL of 24 hours instead of an in-memory Set.
Use HTTPS
Webhook endpoint URLs must use HTTPS. This ensures the payload is encrypted in transit and prevents man-in-the-middle attacks.
Handle Retries Gracefully
If your endpoint is temporarily unavailable, bitbybit will retry with exponential backoff. Make sure your processing logic is idempotent — processing the same event twice should produce the same result.
Monitor Your Endpoints
Check the Delivery History in Settings > Developer to monitor webhook health. Watch for:
- High failure rates (check server logs)
- Slow response times (optimize your handler)
- Suspended endpoints (reactivate after fixing the issue)
Prevent Timeouts
bitbybit will wait up to 30 seconds for a response. If your handler needs more time:
- Acknowledge the webhook immediately with a
200 response
- Process the event in a background job or queue
- Track processing status separately
Test Before Going Live
Use the Send Test button in webhook settings to verify your endpoint is correctly:
- Receiving the POST request
- Parsing the JSON payload
- Verifying the signature
- Returning a 2xx response
Firewall Configuration
If your server has a firewall, ensure it allows incoming POST requests from bitbybit’s servers. The User-Agent header is always BitByBit-Webhooks/1.0.
