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 laterapp.post('/webhooks', (req, res) => { res.status(200).send('OK'); queue.push(req.body); // Process asynchronously});// Bad - processing blocks the responseapp.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');});
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.
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.