> ## 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.

# Webhooks Overview

> Receive real-time event notifications via HTTP POST

## 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:**

```json theme={null}
{
  "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

| Event                    | Description                       |
| ------------------------ | --------------------------------- |
| `customer.created`       | A new customer was created        |
| `customer.updated`       | A customer's details were updated |
| `customer.deleted`       | A customer was deleted            |
| `order.created`          | A new order was created           |
| `order.updated`          | An order was updated              |
| `product.created`        | A new product was created         |
| `product.updated`        | A product was updated             |
| `product.deleted`        | A product was deleted             |
| `message.received`       | An inbound message was received   |
| `message.status.updated` | A message delivery status changed |

## Retry Policy

If your endpoint returns a non-2xx response or times out, bitbybit will retry delivery:

| Attempt   | Delay      |
| --------- | ---------- |
| 1st retry | 30 seconds |
| 2nd retry | 5 minutes  |
| 3rd retry | 30 minutes |
| 4th retry | 2 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