Webhooks
What it is
Webhooks are BotBat's event-driven notification system that pushes real-time updates to your server whenever something significant happens on the platform. Instead of polling the API repeatedly to check for changes, you register an HTTPS endpoint, select the event types you care about, and BotBat sends structured JSON payloads to your server the moment an event occurs. Every payload is signed with an HMAC-SHA256 signature so your server can verify that the request genuinely originated from BotBat.
The webhook system includes a robust retry policy with exponential backoff. If your endpoint is temporarily unavailable or returns a non-2xx status code, BotBat automatically retries delivery up to five times over a 12-hour window. Each delivery attempt is logged in the BotBat console with the event type, HTTP status code from your server, response time, and retry count, giving you full visibility into delivery health.
Webhooks are the foundation of event-driven integrations with BotBat. They power use cases ranging from real-time CRM synchronization and delivery status dashboards to compliance audit trails and automated follow-up workflows. By subscribing only to the events your integration needs, you keep your server's processing load minimal while still reacting instantly to the events that matter most.
When to use
| Scenario | Description |
|---|---|
| Syncing data with external systems | Automatically push contact changes to your CRM, data warehouse, or marketing automation tool when contacts are created or updated in BotBat. |
| Triggering downstream workflows | Kick off follow-up actions in your backend when a campaign completes or a conversation is resolved. For example, update an order status or send a satisfaction survey. |
| Monitoring message delivery in real time | Subscribe to message.delivered and message.read events to update delivery dashboards or trigger time-sensitive follow-ups. |
| Auditing events externally | Forward events to a logging or SIEM system for compliance, security monitoring, or custom analytics beyond BotBat's built-in reporting. |
| Debugging integration issues | Use webhook logs and the testing tools to verify that events are being sent, received, and processed correctly during development. |
Steps
1. Navigate to Webhooks
Go to Developer > Webhooks in the sidebar. The main view shows a table of all configured webhook endpoints, including each endpoint's name, URL, active event count, and current status (active or disabled).
2. Create a webhook endpoint
Click Add Endpoint to open the creation form. Enter your server's HTTPS URL (plain HTTP is not supported for security reasons), give the endpoint a descriptive name such as "CRM Contact Sync" or "Delivery Status Tracker," and select the event types that should trigger notifications to this endpoint. You can select individual events or use Select All for a catch-all endpoint that receives every event type.
Only HTTPS endpoints with valid SSL certificates from trusted Certificate Authorities are accepted. Self-signed certificates will be rejected. If you are developing locally, use a tunneling tool such as ngrok to expose your local server with a valid HTTPS URL.
3. Copy the signing secret
After saving the endpoint, BotBat generates a unique signing secret. This secret is displayed once. Copy it immediately and store it in a secure location such as an environment variable or secrets manager. You will use this secret on your server to verify that incoming webhook payloads are authentic.
4. Implement signature verification
On your server, compute an HMAC-SHA256 hash of the raw request body using the signing secret as the key. Compare the resulting hex digest to the value in the X-BotBat-Signature header of the incoming request. If they match, the payload is authentic. If they do not match, reject the request with an HTTP 401 response. The following table summarizes the signature verification steps.
| Step | Action |
|---|---|
| 1 | Read the raw request body as a byte string (do not parse JSON first). |
| 2 | Retrieve the X-BotBat-Signature header value from the request. |
| 3 | Compute HMAC-SHA256 of the raw body using your signing secret as the key. |
| 4 | Compare your computed hex digest with the header value using a constant-time comparison function. |
| 5 | If the values match, process the payload. If they do not match, return HTTP 401 and discard the request. |
5. Process the payload
Parse the JSON body. Every webhook payload follows a consistent structure with four top-level fields.
| Field | Type | Description |
|---|---|---|
event | string | The event type identifier, e.g., message.delivered or contact.created. |
timestamp | string (ISO 8601) | The UTC timestamp when the event occurred. |
webhook_id | string | A unique identifier for this specific delivery. Use this for idempotency checks. |
data | object | The event-specific payload containing the relevant resource data. |
Example payload:
{
"event": "message.delivered",
"timestamp": "2026-02-11T14:30:00.000Z",
"webhook_id": "wh_evt_abc123def456",
"data": {
"message_id": "msg_789xyz",
"contact_id": "ct_456abc",
"channel": "whatsapp",
"delivered_at": "2026-02-11T14:29:58.000Z"
}
}
6. Return a 2xx response
Your endpoint must return an HTTP 2xx status code within 30 seconds to acknowledge receipt. Any non-2xx status code, or a timeout exceeding 30 seconds, triggers the retry policy. Best practice is to accept the webhook immediately (return 200 with an empty body or {"ok": true}), then process the event asynchronously using a job queue or background worker.
7. Monitor webhook logs
In the BotBat console, open the Logs tab for any webhook endpoint. Each delivery attempt is logged with the event type, the HTTP status code your server returned, the response time in milliseconds, and the retry count. You can filter logs by event type, status (success, failed, retrying), and date range.
Click on any log entry to expand it and view the full request payload that was sent, the response body your server returned, and any error details. This is invaluable for debugging failed deliveries.
8. Test locally
Use the Send Test Event button to send a sample payload for any event type to your endpoint. This generates a realistic test payload and delivers it immediately, regardless of whether any real events have occurred. Combined with a tunneling tool like ngrok, this lets you iterate rapidly on your webhook handler without deploying to a remote server.
Event types
The following table lists all available webhook event types. Subscribe only to the events your integration needs to minimize unnecessary processing on your server.
| Event | Trigger | Typical use case |
|---|---|---|
message.received | A new inbound message arrives from a contact. | Route incoming messages to your support system or chatbot. |
message.sent | An outbound message is sent to a contact. | Log outbound activity in your CRM. |
message.delivered | An outbound message is confirmed delivered to the contact's device. | Update delivery dashboards in real time. |
message.read | An outbound message is read by the contact. | Trigger time-sensitive follow-ups or measure engagement. |
campaign.completed | A campaign finishes sending to all recipients. | Generate post-campaign analytics or notify stakeholders. |
contact.created | A new contact is created in BotBat. | Sync the contact to your CRM or data warehouse. |
contact.updated | An existing contact's fields are updated. | Keep external systems in sync with the latest contact data. |
conversation.assigned | A conversation is assigned to an agent. | Notify the agent via Slack, email, or your internal tools. |
conversation.resolved | A conversation is marked as resolved. | Trigger a satisfaction survey or close a support ticket. |
Retry policy
When your endpoint fails to return a 2xx response, BotBat retries with exponential backoff according to the following schedule.
| Attempt | Delay after previous failure |
|---|---|
| 1st retry | 1 minute |
| 2nd retry | 5 minutes |
| 3rd retry | 30 minutes |
| 4th retry | 2 hours |
| 5th retry | 12 hours |
After 5 consecutive failed retries, the event is permanently marked as "failed" in the webhook logs. If an endpoint fails consistently for 72 hours across multiple events, BotBat automatically disables the endpoint and sends an email notification to all workspace administrators. You can re-enable a disabled endpoint from the Webhooks settings page after resolving the underlying issue.
Common pitfalls
| Pitfall | Impact | Recommendation |
|---|---|---|
| Not verifying webhook signatures | Any party who discovers your endpoint URL can send fake events, potentially corrupting your data. | Always validate the X-BotBat-Signature header using HMAC-SHA256 with your signing secret. |
| Processing webhooks synchronously | Slow operations (database writes, external API calls) before returning a response may cause timeouts and trigger unnecessary retries. | Return a 2xx response immediately, then process the event asynchronously via a job queue. |
| Not handling duplicate deliveries | Network issues can cause the same event to be delivered more than once, leading to duplicate records or double-processed actions. | Use the webhook_id field for idempotency. Check whether you have already processed a given ID before acting on it. |
| Using HTTP instead of HTTPS | BotBat rejects non-HTTPS endpoints. Self-signed certificates are also rejected. | Use a valid SSL certificate from a trusted Certificate Authority. For local development, use a tunneling tool. |
| Subscribing to all events unnecessarily | Receiving events your integration does not use wastes bandwidth and processing resources on your server. | Subscribe only to the specific event types your integration requires. |
During development, use the "Send Test Event" button combined with a tunneling tool like ngrok to test your webhook handler locally. This lets you iterate quickly without deploying to a server after every change.
- Webhook Endpoints
- Create Endpoint
- Signing Secret
- Event Types
- Delivery Logs
- Test Event
- Retry Policy
- Signature Verification