Webhook Events

When events occur in Casey (e.g., a conversation starts or completes), we send HTTP POST requests to your configured webhook endpoints. Each event includes a standard envelope with event-specific data.

Envelope format

All webhook events follow this structure:

{
  "event_type": "conversation.started",
  "event_id": "evt_1234567890",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": { ... }
}

Field	Type	Description
`event_type`	string	One of: `conversation.started`, `conversation.completed`, `conversation.abandoned`, `test.event`
`event_id`	string	Unique identifier for idempotency
`timestamp`	string (ISO 8601)	When the event occurred
`organization_id`	string (UUID)	Organization that owns the resource
`data`	object	Event-specific payload (see below)

conversation.started

Fired when a conversation begins.

{
  "event_type": "conversation.started",
  "event_id": "evt_1234567890",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "conversation_id": "660e8400-e29b-41d4-a716-446655440001",
    "project_id": "770e8400-e29b-41d4-a716-446655440002",
    "agent_id": "880e8400-e29b-41d4-a716-446655440003",
    "participant_user_id": "990e8400-e29b-41d4-a716-446655440004",
    "connection_code": "ABC123",
    "started_at": "2024-01-15T10:30:00Z",
    "session_properties": {},
    "path_taken": null,
    "participant_profile": {
      "id": "990e8400-e29b-41d4-a716-446655440004",
      "email": "user@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "organization_name": null,
      "organization_domain": null,
      "avatar_url": null
    }
  }
}

Data fields

Field	Type	Description
`conversation_id`	string (UUID)	Unique identifier for the conversation
`project_id`	string (UUID)	Project the conversation belongs to
`agent_id`	string (UUID)	Agent handling the conversation
`participant_user_id`	string \| null	User ID of the participant (if authenticated)
`connection_code`	string \| null	Connection code used to join
`started_at`	string (ISO 8601)	When the conversation started
`session_properties`	object	Custom session properties set at conversation start
`path_taken`	array \| null	Sections visited during the conversation
`participant_profile`	object \| null	Participant profile details (if available)

conversation.completed

Fired when a conversation finishes successfully. Includes duration and turn count metrics.

{
  "event_type": "conversation.completed",
  "event_id": "evt_1234567891",
  "timestamp": "2024-01-15T10:45:00Z",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "conversation_id": "660e8400-e29b-41d4-a716-446655440001",
    "project_id": "770e8400-e29b-41d4-a716-446655440002",
    "agent_id": "880e8400-e29b-41d4-a716-446655440003",
    "participant_user_id": "990e8400-e29b-41d4-a716-446655440004",
    "started_at": "2024-01-15T10:30:00Z",
    "completed_at": "2024-01-15T10:45:00Z",
    "duration_seconds": 900,
    "turn_count": 24,
    "transcript_markdown": "## Conversation Transcript\n\n**Agent:** Hello!...",
    "session_properties": {},
    "path_taken": [
      { "id": "section-1", "label": "Introduction", "section_type": "intro" }
    ],
    "participant_profile": {
      "id": "990e8400-e29b-41d4-a716-446655440004",
      "email": "user@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  }
}

Data fields

Includes all fields from conversation.started, plus:

Field	Type	Description
`completed_at`	string (ISO 8601)	When the conversation completed
`duration_seconds`	integer	Total duration in seconds
`turn_count`	integer	Number of conversation turns
`transcript_markdown`	string \| null	Full transcript in markdown format

conversation.abandoned

Fired when a conversation is abandoned before completion.

{
  "event_type": "conversation.abandoned",
  "event_id": "evt_1234567892",
  "timestamp": "2024-01-15T10:35:00Z",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "conversation_id": "660e8400-e29b-41d4-a716-446655440001",
    "project_id": "770e8400-e29b-41d4-a716-446655440002",
    "agent_id": "880e8400-e29b-41d4-a716-446655440003",
    "participant_user_id": null,
    "started_at": "2024-01-15T10:30:00Z",
    "abandoned_at": "2024-01-15T10:35:00Z",
    "reason": "disconnect"
  }
}

Data fields

Field	Type	Description
`conversation_id`	string (UUID)	Unique identifier for the conversation
`project_id`	string (UUID)	Project the conversation belongs to
`agent_id`	string (UUID)	Agent that was handling the conversation
`participant_user_id`	string \| null	User ID of the participant (if authenticated)
`started_at`	string (ISO 8601)	When the conversation started
`abandoned_at`	string (ISO 8601)	When the conversation was abandoned
`reason`	string	One of: `timeout`, `disconnect`, `user_left`, `error`

test.event

Test event for verifying webhook endpoint connectivity. Sent via POST /webhooks/test.

{
  "event_type": "test.event",
  "event_id": "test_1705318200000",
  "timestamp": "2024-01-15T10:30:00Z",
  "organization_id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "test": true,
    "message": "This is a test webhook from Casey"
  }
}

Data fields

Field	Type	Description
`test`	boolean	Always `true` for test events
`message`	string	Test message from Casey

Webhook Events

On this page