---
sidebar_position: 2
title: Event Catalog
description: Complete reference of all Firetell webhook event types, payloads, and triggers.
---

# Webhook Event Catalog

Detailed payloads and schemas for all webhook events supported by Firetell.

---

## Call Events

### `call.created`

Triggered immediately when a new call (inbound or outbound) is initiated.

```json
{
  "event": "call.created",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:00:00.000Z",
    "attempt": 1,
    "call_id": "call_abc123",
    "direction": "inbound",
    "status": "started",
    "type": "audio",
    "from": {
      "name": "+84901234567",
      "number": "+84901234567"
    },
    "to": {
      "name": "Support Line",
      "number": "+84909876543"
    },
    "started_at": "2026-07-21T12:00:00.000Z",
    "answered_at": null,
    "ended_at": null,
    "duration": 0,
    "billsec": 0,
    "hangup_cause": null
  }
}
```

---

### `call.answered`

Triggered whenever a call transitions to answered state.

```json
{
  "event": "call.answered",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:00:05.000Z",
    "attempt": 1,
    "call_id": "call_abc123",
    "direction": "inbound",
    "status": "active",
    "type": "audio",
    "from": {
      "name": "+84901234567",
      "number": "+84901234567"
    },
    "to": {
      "name": "Support Line",
      "number": "+84909876543"
    },
    "started_at": "2026-07-21T12:00:00.000Z",
    "answered_at": "2026-07-21T12:00:05.000Z",
    "ended_at": null,
    "duration": 5,
    "billsec": 0,
    "hangup_cause": null
  }
}
```

---

### `call.ended`

Triggered when a call hangs up or fails.

```json
{
  "event": "call.ended",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:02:30.000Z",
    "attempt": 1,
    "call_id": "call_abc123",
    "direction": "inbound",
    "status": "completed",
    "type": "audio",
    "from": {
      "name": "+84901234567",
      "number": "+84901234567"
    },
    "to": {
      "name": "Support Line",
      "number": "+84909876543"
    },
    "started_at": "2026-07-21T12:00:00.000Z",
    "answered_at": "2026-07-21T12:00:05.000Z",
    "ended_at": "2026-07-21T12:02:30.000Z",
    "duration": 150,
    "billsec": 145,
    "hangup_cause": "NORMAL_CLEARING"
  }
}
```

---

### `call.recording.ready`

Triggered when audio recording processing completes and the cloud media file URL is ready for playback and download.

```json
{
  "event": "call.recording.ready",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:02:35.000Z",
    "attempt": 1,
    "recording_id": "rec_call_abc123",
    "call_id": "call_abc123",
    "url": "https://storage.firetell.app/workspaces/ws_company/recordings/call_abc123.mp3",
    "duration": 145,
    "size_bytes": 1160000,
    "format": "mp3",
    "created_at": "2026-07-21T12:02:35.000Z"
  }
}
```

---

### `call.transcription.completed`

Triggered when real-time AI transcription completes and full dialogue text with extracted entities (NER) is compiled.

```json
{
  "event": "call.transcription.completed",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:02:36.000Z",
    "attempt": 1,
    "call_id": "call_abc123",
    "dialogues": [
      {
        "id": "diag_01h900000000000000000001",
        "speaker": "caller",
        "channel_index": 0,
        "text": "Hello, I would like to check my order status for #FT10294.",
        "confidence": 0.98,
        "duration_ms": 3200,
        "timestamp": "2026-07-21T12:00:10.000Z"
      },
      {
        "id": "diag_01h900000000000000000002",
        "speaker": "agent",
        "channel_index": 1,
        "text": "Certainly! I have retrieved order #FT10294 for Alex Rivera. It is scheduled for delivery today with Express Courier.",
        "confidence": 0.99,
        "duration_ms": 5400,
        "timestamp": "2026-07-21T12:00:20.000Z"
      }
    ],
    "entities": [
      {
        "type": "order_id",
        "value": "#FT10294",
        "confidence": 0.99
      },
      {
        "type": "customer_name",
        "value": "Alex Rivera",
        "confidence": 0.98
      },
      {
        "type": "carrier",
        "value": "Express Courier",
        "confidence": 0.97
      }
    ],
    "total_dialogues": 2,
    "completed_at": "2026-07-21T12:02:36.000Z"
  }
}
```

---

### `call.transcription.summary`

Triggered when AI post-call processing completes, providing executive call summary, customer sentiment analysis, and actionable next steps.

```json
{
  "event": "call.transcription.summary",
  "workspace_id": "ws_company",
  "timestamp": "2026-07-21T12:02:40.000Z",
  "data": {
    "transcription_id": "trans_01h900000000000000000001",
    "call_id": "call_abc123",
    "workspace_id": "ws_company",
    "summary": "Customer inquired about enterprise cloud contact center solutions and pricing.",
    "sentiment": "positive",
    "action_items": [
      "Send Enterprise pricing sheet to customer",
      "Schedule live product demo"
    ],
    "language": "en"
  }
}
```

---

## Contact Events

### `contact.created`

Triggered whenever a new contact is created in the workspace.

```json
{
  "event": "contact.created",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:10:00.000Z",
    "attempt": 1,
    "id": "ct_987654321",
    "address_book_id": "ab_sales_vip",
    "first_name": "Nguyen",
    "last_name": "Van A",
    "company": "Acme Corp",
    "phone_numbers": [
      {
        "phone_number": "+84901234567",
        "normalized_number": "84901234567",
        "type": "mobile",
        "is_primary": true
      }
    ],
    "emails": [],
    "assigned_agent_id": "ag_john",
    "created_at": "2026-07-21T12:10:00.000Z"
  }
}
```

---

### `contact.updated`

Triggered whenever contact details or address book assignment are modified.

```json
{
  "event": "contact.updated",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:15:00.000Z",
    "attempt": 1,
    "id": "ct_987654321",
    "address_book_id": "ab_sales_vip",
    "first_name": "Nguyen",
    "last_name": "Van A",
    "company": "Acme Global",
    "title": "CTO",
    "updated_at": "2026-07-21T12:15:00.000Z"
  }
}
```

---

### `contact.deleted`

Triggered when a contact is permanently removed.

```json
{
  "event": "contact.deleted",
  "data": {
    "workspace_id": "ws_company",
    "occurred_at": "2026-07-21T12:20:00.000Z",
    "attempt": 1,
    "id": "ct_987654321",
    "address_book_id": "ab_sales_vip"
  }
}
```

---

## Agent Events

### `agent.state`

Triggered whenever an agent's presence state (available, busy, away, offline) changes.

```json
{
  "event": "agent.state",
  "workspace_id": "ws_company",
  "data": {
    "id": "650000000000000000000001",
    "username": "agent_john",
    "state": "busy",
    "reason": "On call",
    "changed_by": "supervisor_mary"
  },
  "timestamp": "2026-08-03T15:20:00.000Z",
  "attempt": 1
}
```

### `agent.created` / `agent.updated` / `agent.deleted`

Triggered whenever a workspace agent account is created, updated, or deleted.

```json
{
  "event": "agent.created",
  "workspace_id": "ws_company",
  "data": {
    "id": "650000000000000000000001",
    "username": "agent_john",
    "display_name": "John Doe",
    "email": "john@company.com",
    "role": "agent",
    "avatar": "https://cdn.firetell.com/avatars/agent_john.png",
    "country_code": "US",
    "is_active": true
  },
  "timestamp": "2026-08-03T15:20:00.000Z",
  "attempt": 1
}
```

---

## Workspace & Billing Events

### `workspace.credit.updated`

Triggered whenever the workspace credit balance changes (e.g., when an outbound call charge is deducted or when credits are added).

```json
{
  "event": "workspace.credit.updated",
  "workspace_id": "ws_company",
  "timestamp": "2026-08-14T11:36:00.000Z",
  "attempt": 1,
  "data": {
    "workspace_id": "ws_company",
    "credit_balance": 124.85,
    "currency": "USD",
    "amount": -0.055,
    "type": "charge",
    "description": "Outbound call to destination_number: +12025550143 (duration: 60s / 1 mins, from_number: 13133670411)",
    "call_id": "call_1786704938",
    "timestamp": "2026-08-14T11:36:00.000Z"
  }
}
```

---

## Message (SMS/MMS) Events

### `message.received`

Triggered when an incoming SMS or MMS message is received on one of your workspace phone numbers.

```json
{
  "event": "message.received",
  "workspace_id": "yourcompany",
  "timestamp": "2026-09-26T00:00:00.000Z",
  "attempt": 1,
  "data": {
    "id": "msg_be52701819fa34a72ae414",
    "phone_number_id": "pn_99bf875464f1c096f46aff",
    "direction": "inbound",
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Hello, I need assistance with my reservation.",
    "status": "received",
    "media_urls": [],
    "created_at": "2026-09-26T00:00:00.000Z"
  }
}
```

---

### `message.sent`

Triggered when an outbound SMS or MMS message has been accepted by the telecommunications carrier and dispatched for delivery.

```json
{
  "event": "message.sent",
  "workspace_id": "yourcompany",
  "timestamp": "2026-09-26T00:00:02.000Z",
  "attempt": 1,
  "data": {
    "id": "msg_05f18045cba1452204774f",
    "phone_number_id": "pn_e71c8caddbe5603f1d0522",
    "direction": "outbound",
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "status": "sent",
    "error_code": null,
    "error_message": null,
    "created_at": "2026-09-26T00:00:00.000Z",
    "updated_at": "2026-09-26T00:00:02.000Z"
  }
}
```

---

### `message.delivered`

Triggered when the destination carrier confirms successful delivery of the message to the recipient's handset (Delivery Receipt - DLR).

```json
{
  "event": "message.delivered",
  "workspace_id": "yourcompany",
  "timestamp": "2026-09-26T00:00:05.000Z",
  "attempt": 1,
  "data": {
    "id": "msg_05f18045cba1452204774f",
    "phone_number_id": "pn_e71c8caddbe5603f1d0522",
    "direction": "outbound",
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "status": "delivered",
    "error_code": null,
    "error_message": null,
    "created_at": "2026-09-26T00:00:00.000Z",
    "updated_at": "2026-09-26T00:00:05.000Z"
  }
}
```

---

### `message.failed`

Triggered when an outbound SMS/MMS message fails to send or cannot be delivered by the carrier (e.g. invalid destination number, carrier unreachable, or message blocked).

```json
{
  "event": "message.failed",
  "workspace_id": "yourcompany",
  "timestamp": "2026-09-26T00:00:04.000Z",
  "attempt": 1,
  "data": {
    "id": "msg_05f18045cba1452204774f",
    "phone_number_id": "pn_e71c8caddbe5603f1d0522",
    "direction": "outbound",
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "status": "failed",
    "error_code": "40001",
    "error_message": "Destination unreachable: Handset turned off or out of coverage",
    "created_at": "2026-09-26T00:00:00.000Z",
    "updated_at": "2026-09-26T00:00:04.000Z"
  }
}
```

---

### `message.undelivered`

Triggered when a delivery outcome could not be definitively confirmed by the carrier within the receipt timeout window.

```json
{
  "event": "message.undelivered",
  "workspace_id": "yourcompany",
  "timestamp": "2026-09-26T00:05:00.000Z",
  "attempt": 1,
  "data": {
    "id": "msg_05f18045cba1452204774f",
    "phone_number_id": "pn_e71c8caddbe5603f1d0522",
    "direction": "outbound",
    "from": "+13074295456",
    "to": "+18647123123",
    "body": "Your appointment is confirmed for tomorrow at 10:00 AM.",
    "status": "undelivered",
    "error_code": null,
    "error_message": null,
    "created_at": "2026-09-26T00:00:00.000Z",
    "updated_at": "2026-09-26T00:05:00.000Z"
  }
}
```