Webhooks Overview

Webhooks allow your application to receive real-time HTTP notifications when events occur in Bota. Instead of polling the API to check for status changes, webhooks push updates to your server as they happen.

Why Use Webhooks?

Approach	Pros	Cons
Polling	Simple to implement	Wastes resources, delayed updates
Webhooks	Real-time, efficient	Requires endpoint setup

Bota’s async processing model (transcription, summarization) makes webhooks essential. When a transcription completes — which may take seconds to minutes — you’ll know immediately.

Quick Start

1. Create a Webhook Endpoint

Build an HTTP endpoint that accepts POST requests:

const express = require('express');
const app = express();

app.post('/webhooks/bota', express.raw({ type: 'application/json' }), (req, res) => {
  const event = JSON.parse(req.body);

  console.log('Received event:', event.type);

  // Handle the event
  switch (event.type) {
    case 'transcription.completed':
      handleTranscriptionComplete(event.data);
      break;
    case 'recording.uploaded':
      handleRecordingUploaded(event.data);
      break;
  }

  // Return 200 quickly, process async
  res.status(200).send('OK');
});

app.listen(3000);

from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/bota', methods=['POST'])
def handle_webhook():
    event = request.json

    print(f"Received event: {event['type']}")

    # Handle the event
    if event['type'] == 'transcription.completed':
        handle_transcription_complete(event['data'])
    elif event['type'] == 'recording.uploaded':
        handle_recording_uploaded(event['data'])

    # Return 200 quickly, process async
    return 'OK', 200

if __name__ == '__main__':
    app.run(port=3000)

2. Register the Webhook

curl -X POST https://api.bota.dev/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/bota",
    "events": ["transcription.completed", "recording.uploaded"]
  }'

Response:

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/bota",
  "events": ["transcription.completed", "recording.uploaded"],
  "secret": "whsec_xyz789...",
  "created_at": "2025-01-15T10:00:00Z"
}

Save the secret — you’ll need it to verify webhook signatures. It’s only shown once.

3. Verify Signatures

Always verify that webhooks are from Bota. See Signature Verification below.

Event Types

Event	Trigger	Common Use Case
`recording.created`	Recording entry created	Track new recordings
`recording.uploaded`	Audio upload completed	Trigger processing
`recording.deleted`	Recording deleted	Clean up cached data
`transcription.started`	Transcription begins	Show processing status
`transcription.completed`	Transcription finished	Display results to user
`transcription.failed`	Transcription failed	Alert, retry, or fallback
`summary.started`	Summary generation begins	Show processing status
`summary.completed`	Summary generated	Update UI, send notifications
`summary.failed`	Summary generation failed	Alert or retry

See Webhook Events for detailed payload schemas.

Payload Structure

All webhook payloads follow this structure:

{
  "id": "evt_abc123",
  "type": "transcription.completed",
  "created_at": "2025-01-15T10:30:00Z",
  "data": {
    "id": "txn_abc123",
    "recording_id": "rec_xyz789",
    "status": "completed",
    // ... event-specific fields
  }
}

Field	Description
`id`	Unique event identifier (use for deduplication)
`type`	Event type string
`created_at`	When the event occurred (ISO 8601)
`data`	Event-specific payload

Signature Verification

All webhooks are signed using HMAC-SHA256. Always verify signatures to ensure requests are from Bota.

Signature Header

X-Bota-Signature: sha256=a1b2c3d4e5f6...

Verification Code

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');

  const actualSignature = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature),
    Buffer.from(actualSignature)
  );
}

// Express middleware
app.post('/webhooks/bota', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-bota-signature'];

  if (!verifyWebhookSignature(req.body, signature, process.env.WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  // Process event...

  res.status(200).send('OK');
});

import hmac
import hashlib
from flask import Flask, request, abort

def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()

    actual_signature = signature.replace('sha256=', '')

    return hmac.compare_digest(expected_signature, actual_signature)

@app.route('/webhooks/bota', methods=['POST'])
def handle_webhook():
    signature = request.headers.get('X-Bota-Signature')

    if not verify_webhook_signature(request.data, signature, os.environ['WEBHOOK_SECRET']):
        abort(401)

    event = request.json
    # Process event...

    return 'OK', 200

Never skip signature verification, even in development. Attackers can send fake webhook payloads to trigger unwanted actions.

Retry Policy

Bota retries failed deliveries with exponential backoff:

Attempt	Delay After Failure
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	8 hours

After 6 failed attempts, the event is marked as failed and no further retries occur.

What Counts as Failure?

Non-2xx HTTP response
Request timeout (30 seconds)
Connection refused
TLS/SSL errors

Best Practices

Respond quickly (< 5 seconds)

Return a 200 response immediately, then process the event asynchronously. Long-running processing in the request handler will cause timeouts.

app.post('/webhooks/bota', (req, res) => {
  // Return immediately
  res.status(200).send('OK');

  // Process async
  processEventAsync(req.body);
});

Handle duplicates with idempotency

The same event may be delivered multiple times due to retries. Use the id field to deduplicate:

const processedEvents = new Set();

function handleEvent(event) {
  if (processedEvents.has(event.id)) {
    return; // Already processed
  }

  processedEvents.add(event.id);
  // Process event...
}

For production, store processed event IDs in a database.

Use HTTPS endpoints only

Bota only delivers webhooks to HTTPS URLs. HTTP endpoints are rejected for security.

Handle out-of-order delivery

Events may arrive out of order. Don’t assume recording.uploaded arrives before transcription.completed. Check object state via API if order matters.

Log webhook payloads

Log incoming webhooks for debugging. Include the event ID, type, and any processing errors.

Monitor webhook health

Track your webhook success rate. Frequent failures may indicate endpoint issues.

Testing Webhooks

Local Development

Use a tunneling service like ngrok to receive webhooks locally:

# Start ngrok
ngrok http 3000

# Register the ngrok URL
curl -X POST https://api.bota.dev/v1/webhooks \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://abc123.ngrok.io/webhooks/bota",
    "events": ["transcription.completed"]
  }'

Trigger Test Events

Create a recording and transcription to trigger events:

# Create a recording (triggers recording.created)
curl -X POST https://api.bota.dev/v1/recordings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"end_user_id": "eu_abc123", "device_id": "dev_xyz789"}'

# Start transcription (triggers transcription.completed when done)
curl -X POST https://api.bota.dev/v1/transcriptions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"recording_id": "rec_abc123"}'

Managing Webhooks

List Webhooks

curl https://api.bota.dev/v1/webhooks \
  -H "Authorization: Bearer sk_live_..."

Delete a Webhook

curl -X DELETE https://api.bota.dev/v1/webhooks/wh_abc123 \
  -H "Authorization: Bearer sk_live_..."

Update Events (Delete and Recreate)

To change which events a webhook receives, delete it and create a new one.

Troubleshooting

Not receiving webhooks

Verify the webhook is registered: GET /webhooks
Check that your endpoint is publicly accessible
Ensure you’re returning 2xx status codes
Check your server logs for incoming requests
Verify the events you’re subscribed to match what you expect

Signature verification failing

Ensure you’re using the raw request body, not parsed JSON
Check that you’re using the correct webhook secret
Verify you haven’t modified the payload before verification

Duplicate events

This is expected behavior. Implement idempotency using the event id field.

Events arriving out of order

This is expected. Don’t rely on event ordering. Check resource state via API if needed.

Webhooks Overview

Why Use Webhooks?

Quick Start

1. Create a Webhook Endpoint

2. Register the Webhook

3. Verify Signatures

Event Types

Payload Structure

Signature Verification

Signature Header

Verification Code

Retry Policy

What Counts as Failure?

Best Practices

Testing Webhooks

Local Development

Trigger Test Events

Managing Webhooks

List Webhooks

Delete a Webhook

Update Events (Delete and Recreate)

Troubleshooting

Next Steps

Event Reference

API Reference

​Why Use Webhooks?

​Quick Start

​1. Create a Webhook Endpoint

​2. Register the Webhook

​3. Verify Signatures

​Event Types

​Payload Structure

​Signature Verification

​Signature Header

​Verification Code

​Retry Policy

​What Counts as Failure?

​Best Practices

​Testing Webhooks

​Local Development

​Trigger Test Events

​Managing Webhooks

​List Webhooks

​Delete a Webhook

​Update Events (Delete and Recreate)

​Troubleshooting

​Next Steps

Event Reference

API Reference

Why Use Webhooks?

Quick Start

1. Create a Webhook Endpoint

2. Register the Webhook

3. Verify Signatures

Event Types

Payload Structure

Signature Verification

Signature Header

Verification Code

Retry Policy

What Counts as Failure?

Best Practices

Testing Webhooks

Local Development

Trigger Test Events

Managing Webhooks

List Webhooks

Delete a Webhook

Update Events (Delete and Recreate)

Troubleshooting

Next Steps