Skip to main content

​
What are Webhooks?

Webhooks allow you to receive real-time notifications when events occur in your bitbybit account. Instead of polling the API for changes, bitbybit sends an HTTP POST request to your specified URL whenever a subscribed event happens.

​
How it Works

  1. Register a webhook endpoint in Settings > Developer
  2. Subscribe to the events you want to receive
  3. Receive HTTP POST requests when events occur
  4. Verify the signature to ensure authenticity
  5. Respond with a 2xx status code to acknowledge receipt

​
Setup

​
1. Create a Webhook Endpoint

Go to Settings > Developer in your bitbybit dashboard and click Create Webhook. You’ll need:
  • Endpoint URL: An HTTPS URL that will receive webhook events
  • Events: Select which events you want to subscribe to
After creation, you’ll receive a signing secret — save it securely, as it won’t be shown again.

​
2. Handle Incoming Events

Your endpoint will receive POST requests with this format: 
POST https://your-server.com/webhooks
Content-Type: application/json
User-Agent: BitByBit-Webhooks/1.0
X-BitByBit-Webhook-Id: evt_clxxxxxxxxxxxxxxxxxx
X-BitByBit-Webhook-Event: customer.created
X-BitByBit-Webhook-Timestamp: 1700000000
X-BitByBit-Webhook-Signature: t=1700000000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Payload: 
{
  "id": "cust_abc123",
  "email": "john@example.com",
  "firstName": "John",
  "lastName": "Doe",
  "phoneNumber": "+6281234567890",
  "tags": ["vip"],
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

​
3. Respond Quickly

Return a 2xx status code within 30 seconds to acknowledge the event. Process the event asynchronously if needed.

​
Available Events

EventDescription
customer.createdA new customer was created
customer.updatedA customer’s details were updated
customer.deletedA customer was deleted
order.createdA new order was created
order.updatedAn order was updated
product.createdA new product was created
product.updatedA product was updated
product.deletedA product was deleted
message.receivedAn inbound message was received
message.status.updatedA message delivery status changed

​
Retry Policy

If your endpoint returns a non-2xx response or times out, bitbybit will retry delivery:
AttemptDelay
1st retry30 seconds
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
After 5 failed attempts, the delivery is marked as failed. After 10 consecutive failures across all deliveries, the endpoint is automatically suspended.

​
Limits

  • Maximum 10 webhook endpoints per company
  • Payload size up to 64 KB
  • 30 second timeout per delivery
  • Response body captured up to 4 KB for debugging