Skip to main content

Documentation Index

Fetch the complete documentation index at: https://knowledge.bitbybit.studio/llms.txt

Use this file to discover all available pages before exploring further.

​
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:
  1. Acknowledge the webhook immediately with a 200 response
  2. Process the event in a background job or queue
  3. 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.