Set Up Integrations

What it is

Setting up integrations in BotBat involves three practical activities: creating API keys for programmatic access to the REST API, configuring outgoing webhooks to push event notifications to external systems, and setting up incoming webhooks that let external systems trigger BotBat workflows. This page provides detailed, step-by-step instructions for each activity.

API keys authenticate your custom applications, scripts, and backend services when they call the BotBat REST API. Each key is a long-lived bearer token that you include in the Authorization header of every HTTP request. You can create multiple keys with descriptive names, track their usage, and revoke them individually when they are no longer needed.

Webhooks enable event-driven architecture. Outgoing webhooks send an HTTP POST request to your endpoint whenever a selected event occurs in BotBat (such as a message being delivered or a campaign completing). Incoming webhooks work in reverse: your external system sends a POST request to a BotBat-generated URL, which triggers a workflow inside the platform. Together, these mechanisms let you build real-time, loosely coupled integrations without polling.

When to use

Building a custom integration. When your engineering team needs to send messages, manage contacts, or trigger workflows from your own application, start by creating an API key. The key unlocks the full BotBat REST API, which covers messaging, contacts, campaigns, workflows, and analytics endpoints.

Connecting to a notification system. Set up outgoing webhooks to push BotBat events to Slack, PagerDuty, a data warehouse, or any system that accepts HTTP callbacks. For example, you might send a webhook to your analytics platform every time a campaign finishes, or alert your support lead in Slack whenever a conversation has been waiting more than 10 minutes.

Receiving data from external tools. Configure incoming webhooks so that external systems like Shopify, Stripe, or your internal CRM can send data to BotBat and trigger automated workflows. An e-commerce platform can notify BotBat of a new order, which then triggers a WhatsApp confirmation message to the customer.

Rotating credentials for security compliance. Security best practices require periodic key rotation. The API key management interface supports zero-downtime rotation: create a new key, update your application, verify it works, then revoke the old key.

API Keys

Creating and managing API keys

1. Navigate to API Keys. Go to Integrations in the sidebar and click the "API Keys" tab. The list shows all existing keys with their names, creation dates, and last-used timestamps.

2. Create a new API key. Click "Create API Key." Enter a descriptive name that identifies the integration or environment (for example, "CRM Integration - Production" or "Staging Test Key"). Optionally set an expiration date. Click "Create."

3. Copy the key immediately. The full API key value is displayed only once, at creation time. Click the copy button and store the key in a secure location such as a secrets manager, a password vault, or an environment variable. You cannot view the full key again after closing this dialog.

4. Use the key in API requests. Include the key in the Authorization header of every HTTP request to the BotBat REST API:

   Authorization: Bearer YOUR_API_KEY

   All standard REST API endpoints accept this authentication method. Refer to the BotBat API documentation for the full list of available endpoints.

5. Monitor key usage. The API Keys list displays the last-used timestamp for each key. Keys that have not been used for an extended period may be stale and should be considered for revocation. The table below describes each column in the API Keys list.

Column	Description
Name	The descriptive label you assigned when creating the key
Created	The date and time the key was generated
Last Used	The most recent timestamp when the key was used in an API request
Expires	The expiration date, if one was set; blank if the key has no expiration
Actions	Menu with options to copy the key prefix, rotate, or revoke

6. Rotate a key. To rotate without downtime, create a new key first, update your application to use the new key, verify that API calls succeed with the new key, and then revoke the old key. Never revoke the old key before confirming the new one works.

7. Revoke a key. Click the three-dot menu on any API key and select "Revoke." This immediately invalidates the key. Any subsequent requests using the revoked key will receive a 401 Unauthorized response. Revocation cannot be undone.

Outgoing Webhooks

Adding and configuring webhook endpoints

1. Navigate to Webhooks. Go to Integrations in the sidebar and click the "Webhooks" tab. The panel lists all configured webhooks with their status indicators, endpoint URLs, and subscribed event counts.

2. Add a webhook endpoint. Click "Add Webhook" and fill in the following fields:

Field	Required	Description
Endpoint URL	Yes	The HTTPS URL where BotBat sends event payloads. HTTP URLs are rejected.
Description	No	A brief note explaining the purpose of this webhook (e.g., "Analytics pipeline")
Signing secret	No	A shared secret used to generate an HMAC signature for payload verification

3. Select events to subscribe. Choose which BotBat events should trigger a payload delivery to this endpoint. Only subscribe to the events your endpoint actually processes; subscribing to everything generates unnecessary traffic.

The following table lists the most commonly used webhook events.

Event	Trigger Condition
message.received	A new message arrives from a contact on any channel
message.delivered	A message sent by BotBat is confirmed delivered by the channel provider
message.read	A message is marked as read by the recipient (channels that support read receipts)
conversation.created	A new conversation is initiated by a contact or by the system
conversation.closed	A conversation is marked as closed by an agent or automation
contact.created	A new contact record is added to BotBat
contact.updated	One or more attributes on an existing contact are modified
campaign.completed	A campaign finishes sending all scheduled messages

4. Save and activate. Click "Save." The webhook is immediately active and begins receiving payloads for the selected events.

5. Test delivery. Click "Send Test" to dispatch a sample payload to your endpoint. BotBat displays the HTTP response code and response body returned by your endpoint. A 200 OK response confirms the endpoint is reachable and processing correctly.

6. View delivery logs. Click on a webhook to open its delivery log. Each entry shows the event type, timestamp, HTTP response code, response time in milliseconds, and the full request payload. Use the status filter (success, failed) to isolate issues quickly.

7. Understand retries and failure handling. BotBat retries failed webhook deliveries (any non-2xx response) up to 5 times using exponential backoff. The retry intervals are approximately 10 seconds, 30 seconds, 2 minutes, 10 minutes, and 30 minutes. If all retries fail, the event is logged as permanently failed and no further attempts are made.

Incoming Webhooks (Workflow Triggers)

Incoming webhooks let external systems trigger BotBat workflows by sending an HTTP POST request to a unique URL.

1. Create a workflow with a webhook trigger. On the Workflows page, create a new workflow and select "Webhook" as the trigger type. BotBat automatically generates a unique webhook URL for this workflow.

2. Copy the generated URL. Click the copy button next to the URL. This is the endpoint your external system will call.

3. Configure your external system. Paste the URL into the webhook or notification settings of your external system (for example, Shopify order webhooks, Stripe payment events, or a custom application). When the external system sends a POST request to this URL with a JSON body, the workflow triggers.

4. Map incoming data. In the workflow trigger configuration, define the expected JSON payload structure. This allows you to reference individual fields from the incoming data as variables throughout the workflow steps. For example, if the payload contains {"orderId": "12345", "customerEmail": "user@example.com"}, you can use {{trigger.orderId}} and {{trigger.customerEmail}} in subsequent workflow actions.

Common pitfalls

Not copying the API key at creation. The full key value is displayed only once. If you close the dialog without copying it, you must create a new key. There is no recovery mechanism for lost keys.

Using HTTP instead of HTTPS for webhook endpoints. BotBat requires HTTPS for all webhook endpoints. This ensures that event payloads are encrypted in transit. HTTP URLs are rejected at configuration time.

Subscribing to too many events. Subscribing a webhook to every available event type generates significant traffic, especially if your account processes high message volumes. Only subscribe to the events your endpoint actually needs, and use server-side filtering if you need to process a subset of a broad event category.

Not verifying webhook signatures. If you set a signing secret but do not implement HMAC verification on your endpoint, you cannot confirm that incoming payloads genuinely originate from BotBat. An attacker who discovers your endpoint URL could send forged payloads. Always validate the X-BotBat-Signature header using your signing secret.

Firewall blocking BotBat's outbound IP. If your webhook endpoint is behind a corporate firewall or a cloud security group, you must whitelist BotBat's outbound IP addresses. Contact BotBat support for the current IP ranges and update your firewall rules accordingly.

tip

When building a custom integration, start by creating an API key with a short expiration (for example, 7 days) for development and testing. Once the integration is stable and passes QA, create a long-lived production key and revoke the development one.

• API Keys List
• Create API Key
• Add Webhook
• Event Subscriptions
• Delivery Log
• Incoming Webhooks