---
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": "Hotline",
      "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": "Hotline",
      "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": "Hotline",
      "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.

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

---

## 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
}
```