Webhook Events

This page documents Bota webhook event types, triggers, and payload shapes.

Event Structure

All webhook requests use the same envelope:

{
  "id": "evt_abc123def456",
  "type": "recording.uploaded",
  "created_at": "2026-07-25T11:00:38.119Z",
  "data": {
    "recording": {
      "id": "rec_abc123",
      "status": "uploaded"
    }
  }
}

Field	Type	Description
`id`	string	Unique event ID. Also sent as `X-Bota-Event-Id`; use it for deduplication.
`type`	string	Event type, such as `recording.uploaded`.
`created_at`	string	ISO 8601 timestamp for when the event was created.
`data`	object	Event-specific payload. Resource events wrap the resource by name, such as `data.recording`.

Webhook payloads are notifications, not full resource snapshots. Fetch the recording, transcription, or summary by ID if your handler needs fields that are not included in the webhook.

Recording Events

Recording events include data.recording.

recording.created

Triggered when a recording is created.

{
  "id": "evt_abc123",
  "type": "recording.created",
  "created_at": "2026-07-25T11:00:34.859Z",
  "data": {
    "recording": {
      "id": "rec_abc123",
      "end_user_id": "eu_user123",
      "device_id": "dev_device456",
      "status": "pending",
      "duration_seconds": null,
      "file_size_bytes": null,
      "recorded_at": null,
      "created_at": "2026-07-25T11:00:34.859Z"
    }
  }
}

recording.uploaded

Triggered when audio upload completes successfully.

{
  "id": "evt_def456",
  "type": "recording.uploaded",
  "created_at": "2026-07-25T11:00:38.119Z",
  "data": {
    "recording": {
      "id": "rec_abc123",
      "end_user_id": "eu_user123",
      "device_id": "dev_device456",
      "status": "uploaded",
      "duration_seconds": 45,
      "file_size_bytes": 48575,
      "recorded_at": null,
      "created_at": "2026-07-25T11:00:34.859Z"
    }
  }
}

recording.deleted

Triggered when a recording is deleted.

{
  "id": "evt_rst345",
  "type": "recording.deleted",
  "created_at": "2026-07-25T11:05:00.000Z",
  "data": {
    "recording": {
      "id": "rec_abc123"
    }
  }
}

recording.integrity_failure

Triggered when uploaded audio fails server-side SHA-256 verification.

{
  "id": "evt_integrity123",
  "type": "recording.integrity_failure",
  "created_at": "2026-07-25T11:00:38.119Z",
  "data": {
    "recording": {
      "id": "rec_abc123",
      "status": "uploaded",
      "duration_seconds": 45,
      "file_size_bytes": 48575,
      "recorded_at": null,
      "created_at": "2026-07-25T11:00:34.859Z"
    },
    "expected_sha256": "9b2c...",
    "actual_sha256": "4a7f..."
  }
}

Field	Type	Description
`data.recording.id`	string	Recording ID.
`data.recording.end_user_id`	string or null	Associated EndUser, if any.
`data.recording.device_id`	string or null	Associated device, if any.
`data.recording.status`	string	Current recording status.
`data.recording.duration_seconds`	number or null	Recording duration in seconds, if known.
`data.recording.file_size_bytes`	integer or null	File size in bytes, if known.
`data.recording.recorded_at`	string or null	Device recording time, if known.
`data.recording.created_at`	string	API creation timestamp.
`data.expected_sha256`	string	Hash supplied by the client or device.
`data.actual_sha256`	string	Hash calculated by Bota.

Transcription Events

Transcription events include data.transcription.

transcription.started

Triggered when transcription processing begins.

{
  "id": "evt_uvw678",
  "type": "transcription.started",
  "created_at": "2026-07-25T11:01:00.000Z",
  "data": {
    "transcription": {
      "id": "txn_abc123",
      "recording_id": "rec_abc123",
      "status": "processing",
      "language": "en",
      "word_count": null,
      "confidence": null,
      "error_message": null,
      "created_at": "2026-07-25T11:00:59.000Z",
      "completed_at": null
    }
  }
}

transcription.completed

Triggered when transcription processing completes successfully.

{
  "id": "evt_ghi789",
  "type": "transcription.completed",
  "created_at": "2026-07-25T11:02:30.000Z",
  "data": {
    "transcription": {
      "id": "txn_abc123",
      "recording_id": "rec_abc123",
      "status": "completed",
      "language": "en",
      "word_count": 2847,
      "confidence": 0.98,
      "error_message": null,
      "created_at": "2026-07-25T11:00:59.000Z",
      "completed_at": "2026-07-25T11:02:30.000Z"
    }
  }
}

transcription.failed

Triggered when transcription processing fails.

{
  "id": "evt_jkl012",
  "type": "transcription.failed",
  "created_at": "2026-07-25T11:02:30.000Z",
  "data": {
    "transcription": {
      "id": "txn_abc123",
      "recording_id": "rec_abc123",
      "status": "failed",
      "language": "en",
      "word_count": null,
      "confidence": null,
      "error_message": "Audio quality too low for transcription",
      "created_at": "2026-07-25T11:00:59.000Z",
      "completed_at": null
    }
  }
}

Field	Type	Description
`data.transcription.id`	string	Transcription ID.
`data.transcription.recording_id`	string	Associated recording ID.
`data.transcription.status`	string	Current transcription status.
`data.transcription.language`	string or null	Language code, if known.
`data.transcription.word_count`	integer or null	Word count when completed.
`data.transcription.confidence`	number or null	Provider confidence score, if available.
`data.transcription.error_message`	string or null	Failure reason, if any.
`data.transcription.created_at`	string	API creation timestamp.
`data.transcription.completed_at`	string or null	Completion timestamp, if completed.

Summary Events

Summary events include data.summary.

summary.started

Triggered when summary generation begins.

{
  "id": "evt_xyz012",
  "type": "summary.started",
  "created_at": "2026-07-25T11:03:00.000Z",
  "data": {
    "summary": {
      "id": "sum_def456",
      "transcription_id": "txn_abc123",
      "status": "processing",
      "template_id": "tmpl_general_notes",
      "is_custom_prompt": false,
      "error_message": null,
      "created_at": "2026-07-25T11:02:59.000Z",
      "completed_at": null
    }
  }
}

summary.completed

Triggered when summary generation completes successfully.

{
  "id": "evt_mno345",
  "type": "summary.completed",
  "created_at": "2026-07-25T11:03:30.000Z",
  "data": {
    "summary": {
      "id": "sum_def456",
      "transcription_id": "txn_abc123",
      "status": "completed",
      "template_id": "tmpl_general_notes",
      "is_custom_prompt": false,
      "error_message": null,
      "created_at": "2026-07-25T11:02:59.000Z",
      "completed_at": "2026-07-25T11:03:30.000Z"
    }
  }
}

summary.failed

Triggered when summary generation fails.

{
  "id": "evt_pqr678",
  "type": "summary.failed",
  "created_at": "2026-07-25T11:03:30.000Z",
  "data": {
    "summary": {
      "id": "sum_def456",
      "transcription_id": "txn_abc123",
      "status": "failed",
      "template_id": "tmpl_general_notes",
      "is_custom_prompt": false,
      "error_message": "LLM provider unavailable",
      "created_at": "2026-07-25T11:02:59.000Z",
      "completed_at": null
    }
  }
}

Field	Type	Description
`data.summary.id`	string	Summary ID.
`data.summary.transcription_id`	string	Source transcription ID.
`data.summary.status`	string	Current summary status.
`data.summary.template_id`	string or null	Template used, if any.
`data.summary.is_custom_prompt`	boolean	Whether the summary used a custom prompt.
`data.summary.error_message`	string or null	Failure reason, if any.
`data.summary.created_at`	string	API creation timestamp.
`data.summary.completed_at`	string or null	Completion timestamp, if completed.

Device Events

Device claim events include data.device.

device.claimed

Triggered when a device is claimed through app-less registration.

{
  "id": "evt_claimed123",
  "type": "device.claimed",
  "created_at": "2026-07-25T11:04:00.000Z",
  "data": {
    "device": {
      "id": "dev_device456",
      "serial_number": "BOTA-001",
      "end_user_id": "eu_user123",
      "model": "note",
      "status": "active",
      "provisioning_status": "provisioned",
      "created_at": "2026-07-25T10:55:00.000Z"
    },
    "claimed_at": "2026-07-25T11:04:00.000Z"
  }
}

device.activated

Triggered when a claimed device is activated.

{
  "id": "evt_activated123",
  "type": "device.activated",
  "created_at": "2026-07-25T11:04:05.000Z",
  "data": {
    "device": {
      "id": "dev_device456",
      "serial_number": "BOTA-001",
      "end_user_id": "eu_user123",
      "model": "note",
      "status": "active",
      "provisioning_status": "provisioned",
      "created_at": "2026-07-25T10:55:00.000Z"
    },
    "activated_at": "2026-07-25T11:04:05.000Z"
  }
}

Subscribing to Events

When creating a webhook, specify which events to receive:

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": [
      "recording.created",
      "recording.uploaded",
      "recording.deleted",
      "recording.integrity_failure",
      "transcription.started",
      "transcription.completed",
      "transcription.failed",
      "summary.started",
      "summary.completed",
      "summary.failed",
      "device.claimed",
      "device.activated"
    ]
  }'

Event Delivery Order

Events are delivered in the order they occur, but network conditions may cause out-of-order arrival. Design your handlers to be order-independent. Example Timeline:

recording.created — Recording entry created
recording.uploaded — Audio upload completed
transcription.started — Transcription processing begins
transcription.completed — Transcription finished
summary.started — Summary generation begins
summary.completed — Summary generated

Each event is independent. You may receive transcription.completed before your handler has finished processing recording.uploaded.

Handling Tips

Async Processing

Process events asynchronously to avoid timeouts:

app.post('/webhooks/bota', async (req, res) => {
  res.status(200).send('OK');
  await eventQueue.add('process-webhook', req.body);
});

Type-Safe Handlers

Use TypeScript or schema validation:

type BotaEvent =
  | { id: string; type: 'recording.created'; data: { recording: RecordingData } }
  | { id: string; type: 'recording.uploaded'; data: { recording: RecordingData } }
  | { id: string; type: 'transcription.completed'; data: { transcription: TranscriptionData } }
  | { id: string; type: 'summary.completed'; data: { summary: SummaryData } };

function handleEvent(event: BotaEvent) {
  switch (event.type) {
    case 'recording.uploaded':
      console.log(event.data.recording.id);
      break;
    case 'transcription.completed':
      console.log(event.data.transcription.recording_id);
      break;
  }
}

Webhooks Overview

Setup, verification, and best practices

Create Webhook

API endpoint reference

Getting Started

Features

Hardware

Webhooks

Legal & Compliance

Webhook Events

Event Structure

Recording Events

recording.created

recording.uploaded

recording.deleted

recording.integrity_failure

Transcription Events

transcription.started

transcription.completed

transcription.failed

Summary Events

summary.started

summary.completed

summary.failed

Device Events

device.claimed

device.activated

Subscribing to Events

Event Delivery Order

Handling Tips

Async Processing

Type-Safe Handlers

Webhooks Overview

Create Webhook

​Event Structure

​Recording Events

​recording.created

​recording.uploaded

​recording.deleted

​recording.integrity_failure

​Transcription Events

​transcription.started

​transcription.completed

​transcription.failed

​Summary Events

​summary.started

​summary.completed

​summary.failed

​Device Events

​device.claimed

​device.activated

​Subscribing to Events

​Event Delivery Order

​Handling Tips

​Async Processing

​Type-Safe Handlers

​Related

Webhooks Overview

Create Webhook

Event Structure

Recording Events

recording.created

recording.uploaded

recording.deleted

recording.integrity_failure

Transcription Events

transcription.started

transcription.completed

transcription.failed

Summary Events

summary.started

summary.completed

summary.failed

Device Events

device.claimed

device.activated

Subscribing to Events

Event Delivery Order

Handling Tips

Async Processing

Type-Safe Handlers

Related