Events

This page documents all webhook events sent by KrosAI.

Event Format

All webhook events follow this structure:

{
  "event": "event.type",
  "id": "evt_abc123",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    // Event-specific data
  }
}

Call Events

call.initiated

Sent when a call is initiated (inbound or outbound).

{
  "event": "call.initiated",
  "id": "evt_001",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    "call_id": "call_abc123",
    "direction": "inbound",
    "from_number": "[phone]",
    "to_number": "[phone]",
    "phone_number_id": "pn_123",
    "endpoint_id": "ep_456"
  }
}

call.ringing

Sent when the destination is ringing.

{
  "event": "call.ringing",
  "id": "evt_002",
  "timestamp": "2025-01-10T12:00:01Z",
  "data": {
    "call_id": "call_abc123"
  }
}

call.answered

Sent when the call is answered.

{
  "event": "call.answered",
  "id": "evt_003",
  "timestamp": "2025-01-10T12:00:05Z",
  "data": {
    "call_id": "call_abc123",
    "answered_at": "2025-01-10T12:00:05Z"
  }
}

call.completed

Sent when a call ends normally.

{
  "event": "call.completed",
  "id": "evt_004",
  "timestamp": "2025-01-10T12:03:05Z",
  "data": {
    "call_id": "call_abc123",
    "direction": "inbound",
    "from_number": "[phone]",
    "to_number": "[phone]",
    "duration": 180,
    "cost_cents": 12,
    "hangup_cause": "normal_clearing",
    "recording_url": "https://storage.krosai.com/recordings/call_abc123.mp3",
    "transcript": "Hello, how can I help you today?...",
    "metadata": {
      "customer_id": "cust_123"
    }
  }
}

call.failed

Sent when a call fails to connect.

{
  "event": "call.failed",
  "id": "evt_005",
  "timestamp": "2025-01-10T12:00:30Z",
  "data": {
    "call_id": "call_abc123",
    "direction": "outbound",
    "from_number": "[phone]",
    "to_number": "[phone]",
    "error_code": "NETWORK_ERROR",
    "error_message": "Failed to establish connection"
  }
}

Phone Number Events

phone_number.purchased

Sent when a phone number is purchased.

{
  "event": "phone_number.purchased",
  "id": "evt_010",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    "phone_number_id": "pn_abc123",
    "number": "[phone]",
    "country": "NG",
    "type": "local",
    "monthly_cost_cents": 500
  }
}

phone_number.released

Sent when a phone number is released.

{
  "event": "phone_number.released",
  "id": "evt_011",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    "phone_number_id": "pn_abc123",
    "number": "[phone]"
  }
}

phone_number.updated

Sent when a phone number configuration changes.

{
  "event": "phone_number.updated",
  "id": "evt_012",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    "phone_number_id": "pn_abc123",
    "changes": {
      "endpoint_id": {
        "old": "ep_old",
        "new": "ep_new"
      }
    }
  }
}

Endpoint Events

endpoint.created

{
  "event": "endpoint.created",
  "id": "evt_020",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    "endpoint_id": "ep_abc123",
    "name": "Support Agent",
    "type": "agent",
    "provider": "elevenlabs"
  }
}

endpoint.updated

{
  "event": "endpoint.updated",
  "id": "evt_021",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    "endpoint_id": "ep_abc123",
    "changes": {
      "status": {
        "old": "active",
        "new": "inactive"
      }
    }
  }
}

endpoint.deleted

{
  "event": "endpoint.deleted",
  "id": "evt_022",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    "endpoint_id": "ep_abc123"
  }
}

Recording Events

recording.ready

Sent when a call recording is processed and available.

{
  "event": "recording.ready",
  "id": "evt_030",
  "timestamp": "2025-01-10T12:05:00Z",
  "data": {
    "call_id": "call_abc123",
    "recording_url": "https://storage.krosai.com/recordings/call_abc123.mp3",
    "duration_seconds": 180,
    "size_bytes": 2160000
  }
}

transcript.ready

Sent when a call transcript is processed and available.

{
  "event": "transcript.ready",
  "id": "evt_031",
  "timestamp": "2025-01-10T12:05:30Z",
  "data": {
    "call_id": "call_abc123",
    "transcript": "[Agent]: Hello...",
    "word_count": 156,
    "language": "en"
  }
}

Port Request Events

port_request.submitted

{
  "event": "port_request.submitted",
  "id": "evt_040",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    "port_request_id": "pr_abc123",
    "phone_number": "[phone]",
    "current_carrier": "mtn"
  }
}

port_request.completed

{
  "event": "port_request.completed",
  "id": "evt_041",
  "timestamp": "2025-01-25T10:00:00Z",
  "data": {
    "port_request_id": "pr_abc123",
    "phone_number_id": "pn_new123",
    "phone_number": "[phone]"
  }
}

port_request.failed

{
  "event": "port_request.failed",
  "id": "evt_042",
  "timestamp": "2025-01-15T14:00:00Z",
  "data": {
    "port_request_id": "pr_abc123",
    "reason": "Account name mismatch",
    "phone_number": "[phone]"
  }
}

Billing Events

balance.low

Sent when account balance falls below threshold.

{
  "event": "balance.low",
  "id": "evt_050",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    "current_balance_cents": 500,
    "threshold_cents": 1000
  }
}

payment.received

{
  "event": "payment.received",
  "id": "evt_051",
  "timestamp": "2025-01-10T12:00:00Z",
  "data": {
    "amount_cents": 10000,
    "payment_method": "card",
    "new_balance_cents": 10500
  }
}

Event Subscriptions

Configure which events to receive when creating a webhook:

curl -X POST "https://api.krosai.com/v1/webhooks" \
  -H "x-api-key: kros_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.yourapp.com/webhooks/krosai",
    "events": [
      "call.completed",
      "call.failed",
      "recording.ready"
    ]
  }'

Event Wildcards

Subscribe to all events in a category:

• call.* - All call events

• phone_number.* - All phone number events

• * - All events