Event Types

Delivery, signatures & retries

Every event is delivered as an HTTP POST with a JSON body using the standard envelope { event, organization_id, data }. Endpoints are managed in Settings → Webhooks in the dashboard, which also gives you a self-serve portal with full delivery history, per-attempt response codes, and manual replay. Headers. Each delivery carries three headers:

Header	Purpose
`svix-id`	Unique message ID. Stable across retries and manual redeliveries — dedupe on it and your consumer is idempotent.
`svix-timestamp`	Delivery timestamp (Unix seconds). Reject deliveries older than your tolerance window to prevent replay.
`svix-signature`	HMAC-SHA256 signature of `{id}.{timestamp}.{payload}` using your per-endpoint signing secret (`whsec_…`).

Signature verification. Every endpoint has its own signing secret, available from the webhooks portal. Verify the signature on every delivery before trusting the payload; reject anything that fails verification or falls outside your timestamp tolerance. Retries. A delivery is considered failed on any non-2xx response or timeout. Failed deliveries are retried automatically with exponential backoff over several hours; after the automatic schedule is exhausted, manual replay remains available from the portal. Return a 2xx as fast as possible — enqueue the event and process it asynchronously rather than doing work inline. Idempotency. Dedupe on the svix-id header. Phone-call events additionally carry a producer-side idempotency key of the form <event_type>.<session_id> — each phone event type fires at most once per session. conversation.started suppresses duplicate publication attempts for the same organization and session for three days. Delivery retries can still reach your endpoint more than once; dedupe using the header above. Ordering is not guaranteed. Retries mean events can arrive out of order; use the timestamp field in the payload, not arrival order.

conversation.started This event is triggered when a new live session is created, regardless of the channel. It does not wait for a contact message. Historical import jobs do not emit it, and later messages or reopening an existing session do not emit it again. first_message contains the first stored message available at creation, or an empty string ("") if none exists yet. timestamp is the session creation time. channel identifies the session’s actual channel; phone sessions use phone_voice.

{
  event: 'conversation.started';
  organization_id: string;
  data: {
    conversation_id: string;
    assignee:
    | {
      type: 'AI';
      name: string;
    }
    | {
      id: string;
      type: 'human';
      name: string;
      avatar_url: string;
    };
    contact: {
      id?: string;
      name?: string;
      enriched_data?: {
        address?: string | null;
        phone_number?: string;
        email?: string;
      };
      custom_data?: object;
    };
    channel:
      | 'web' | 'email' | 'phone_voice' | 'web_voice'
      | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger'
      | 'api' | 'twitter' | 'twitter_mentions' | 'app_review' | 'internal';
    first_message: string;
    timestamp: string;
  };
}

conversation.closed This event is triggered when a conversation is closed, a conversation can be marked as resolved or not resolved, and can be closed by a human or an AI. closed_by identifies what triggered the close, while assignee identifies who the conversation was assigned to at close time. They are independent: a workflow or AI close on a conversation assigned to a human agent still carries that agent’s details in assignee, so you can attribute the resolution to the assigned agent even when they didn’t close it themselves.

{
    event: "conversation.closed";
    organization_id: string;
    data: {
        conversation_id?: string;
        timestamp: string;
        contact_id?: string;
        contact?: {
          id: string;
          name?: string;
          email?: string;
          phone_number?: string;
          custom_data?: object;
        };
        human_resolution_status: "resolved" | "not_resolved" | null;
        ai_resolution_status: string | null;
        ai_billing_tier: string | null;
        closed_by:
        | {
            type: "AI";
            name: string;
        }
        | {
            id: number;
            type: "human";
            email: string;
        }
        | {
            type: "workflow";
            id: string;
            workflow_run_id: string;
        }
        | {
            type: "contact";
            id: string;
        };
        // Who the conversation was assigned to when it was closed.
        // `alias` / `alias_avatar_url` carry the agent's per-org masked
        // identity when one is configured, null otherwise.
        assignee:
        | {
            type: "AI";
            name: string;
        }
        | {
            type: "human";
            name: string;
            email: string;
            avatar_url: string;
            alias: string | null;
            alias_avatar_url: string | null;
        }
        | {
            type: "unassigned";
        };
        is_from_third_party: boolean;
        third_party_name: "dynamics365" | "freshchat" | "freshdesk" | "gorgias" | "hubspot" | "intercom" | "open" | "salesforce" | "twilio_flex" | "zendesk" | "zendesk_v2" | null;
        summary: string | null | undefined;
        contact_reason: string | null | undefined;
        user_sentiment: string | null | undefined;
        language: string | null | undefined;
    }[];
}

conversation.handoff_to_human This event is triggered when a conversation is handed off to a human agent. Note that a handoff event can happen for multiple reasons; for example, a human agent might decide to take over the conversation, or the AI might decide to hand off the conversation to a human agent.

{
    event: "conversation.handoff_to_human";
    organization_id: string;
    data: {
        conversation_id: string | null | undefined;
        timestamp: string;
        contact?: {
          id: string;
          name?: string;
          email?: string;
          phone_number?: string;
          custom_data?: object;
        };
        reason:
        | "ai_decided_to_handoff_the_conversation"
        | "ai_is_forbidden_from_handling_this_topic"
        | "human_agent_decided_to_take_over"
        | "human_agent_decided_forced_handoff"
        | "ai_decided_to_auto_handoff_the_issue";
        summary: string;
        contact_reason?: string;
        user_sentiment?: string;
        was_handedoff_to_third_party?: boolean;
        during_work_hours?: boolean;
        third_party_name?: "dynamics365" | "freshchat" | "freshdesk" | "gorgias" | "hubspot" | "intercom" | "open" | "salesforce" | "twilio_flex" | "zendesk" | "zendesk_v2" | null;
        message_count: number;
        language: string;
        integration_metadata?: {
           sunshine?: {
             sunshine_conversation_id: string;
           };
        };
    }[];
}

conversation.contact_response When a contact sends a message to your inbox.

{
  event: 'conversation.contact_response';
  organization_id: string;
  data: {
    conversation_id: string;
    timestamp: string;
    response: string;
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
    custom_data?: Record<string, unknown> | null | undefined;
  }
}

conversation.ai_response When an AI responds to a contact message,

{
  event: 'conversation.ai_response';
  organization_id: string;
  data: {
    conversation_id: string;
    timestamp: string;
    response: string;
    contact: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
  }
}

conversation.agent_response When a human agent responds from the Open inbox,

{
  event: 'conversation.agent_response';
  organization_id: string;
  data: {
    conversation_id: string;
    // The reply's message id — what an option tap is reported against.
    message_id: string;
    timestamp: string;
    customer_id?: string;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    response: string;
    // Present when the reply came from a macro with options, on channels
    // that render them (WhatsApp, Messenger, Instagram, API). On API sessions,
    // render them and report a tap with Send a message's `option_reply`.
    options?: Array<{
      id: string;
      label: string;
      type: 'text' | 'workflow';
    }>;
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
    assignee:
    | {
      type: 'AI';
      name: string;
    }
    | {
      type: 'human';
      name: string;
      email: string;
      avatar_url: string;
      // Per-org agent alias, when one is set. Use these to surface a masked
      // identity instead of the agent's real `name`/`avatar_url`. Always
      // present; both are `null` when the agent has no alias in this org.
      alias: string | null;
      alias_avatar_url: string | null;
    }
    | {
      type: 'unassigned';
    };
  }
}

conversation.third_party_agent_response When a third-party software agent responds to a previously handed-off conversation, Open will notify you. In some configurations, Open might also initiate the handoff to a third-party agent, such as Zendesk or Intercom. Even while the third-party agent handles the conversation, Open continues to monitor and send events to your webhooks.

{
  event: 'conversation.third_party_agent_response';
  organization_id: string;
  data: {
    conversation_id: string | null | undefined;
    timestamp: string;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    third_party_name: 'dynamics365' | 'freshchat' | 'freshdesk' | 'gorgias' | 'hubspot' | 'intercom' | 'open' | 'salesforce' | 'twilio_flex' | 'zendesk' | 'zendesk_v2';
    response: string;
    message_count: number;
    language: string;
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
    agent: {
      name?: string;
    };
    attachments?: Array<{ mime_type: string; url: string; file_name?: string }>;
  }
}

conversation.handoff_to_third_party_failed Triggered when a handoff to a third-party platform (e.g. Zendesk, Intercom) fails.

{
  event: 'conversation.handoff_to_third_party_failed';
  organization_id: string;
  data: {
    conversation_id: string;
    timestamp: string;
    third_party_name: 'dynamics365' | 'freshchat' | 'freshdesk' | 'gorgias' | 'hubspot' | 'intercom' | 'open' | 'salesforce' | 'twilio_flex' | 'zendesk' | 'zendesk_v2';
    error: string;
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
    language: string | null;
    custom_data?: object | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
  }
}

workflow.run.succeeded Triggered when a workflow run completes successfully.

{
  event: 'workflow.run.succeeded';
  organization_id: string;
  data: {
    run_id: string;
    workflow_id: string;
    trigger_cause: 'automatic' | 'manual' | 'scheduled';
    triggered_by: number | null;
    is_test_run: boolean;
  }
}

workflow.run.failed Triggered when a workflow run fails.

{
  event: 'workflow.run.failed';
  organization_id: string;
  data: {
    run_id: string;
    workflow_id: string;
    workflow_name: string;
    session_id: string | null;
    trigger_cause: 'automatic' | 'manual' | 'scheduled';
    triggered_by: number | null;
    is_test_run: boolean;
    error: {
      message: string;
      name: string;
    };
  }
}

workflow.dispatch_failed Triggered when a phone call could not hand one of its lifecycle stages to the workflow engine at all — so the workflows listening on those triggers never ran, and no workflow.run.failed can follow (there is no run). This is the only signal for that failure mode; a stage whose workflows did run but failed produces workflow.run.failed instead, never both.

Field	Description
`stage`	Which point in the call failed to dispatch: `call_started`, `pre_transfer`, `post_transfer`, `pre_call_finished`, `call_finished`, or `workflow_tool` (an AI-triggered workflow the agent invoked mid-call).
`trigger_types`	The workflow trigger types that would have fired at that stage (e.g. `["phone-call-finished"]`).
`error`	Why the dispatch failed, in plain text.

{
  event: 'workflow.dispatch_failed';
  organization_id: string;
  data: {
    session_id: string;
    stage: 'call_started' | 'pre_transfer' | 'post_transfer' | 'pre_call_finished' | 'call_finished' | 'workflow_tool';
    trigger_types: string[];
    error: string;
    timestamp: string;
  }
}

csat.requested Triggered when a CSAT survey is sent to a contact (via email, SMS, WhatsApp, Slack, or shown in the web widget).

{
  event: 'csat.requested';
  organization_id: string;
  data: {
    session_id: string;
    contact_id: string | null;
    channel: 'web' | 'email' | 'phone_voice' | 'slack' | 'sms' | 'whatsapp' | 'instagram' | 'messenger' | 'api' | 'web_voice';
    delivery_method: string;
    timestamp: string;
  }
}

csat.score_submitted Triggered when a customer submits or updates a CSAT score for a conversation.

{
  event: 'csat.score_submitted';
  organization_id: string;
  data: {
    csat_id: string;
    session_id: string;
    contact_id: string | null;
    score: number; // 1–5
    comment: string | null;
    channel: string;
    timestamp: string;
  }
}

Phone Call Events

These events are fired for phone calls — both calls handled by AI phone agents and human-only direct-ring calls (see is_human_call). They apply to both inbound and outbound calls. conversation.started fires when the phone session is created; phone_call.started fires when the call starts. Additional calls on an existing session do not emit another conversation.started. Phone calls do not emit conversation.closed — its session message fields (closed_by, is_from_third_party, contact_reason, …) don’t map cleanly to a phone interaction. Listen on phone_call.ended instead, which carries the equivalent resolution and context fields below.

phone_call.started Triggered when a phone call is initiated — either an inbound call is received or an outbound call is placed. The session’s conversation.started event is emitted separately at session creation.

{
  event: 'phone_call.started';
  organization_id: string;
  data: {
    session_id: string;
    phone_agent_id: string | null;   // null for human-only (direct-ring) calls
    phone_agent_name: string | null; // null for human-only (direct-ring) calls
    is_human_call: boolean;          // true when no AI agent was on the call
    direction: 'inbound' | 'outbound';
    from_phone_number: string | null;
    to_phone_number: string | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    timestamp: string;
  }
}

phone_call.answered Triggered when the remote party picks up the call (SIP participant joined).

{
  event: 'phone_call.answered';
  organization_id: string;
  data: {
    session_id: string;
    phone_agent_id: string | null;   // null for human-only (direct-ring) calls
    phone_agent_name: string | null; // null for human-only (direct-ring) calls
    is_human_call: boolean;          // true when no AI agent was on the call
    direction: 'inbound' | 'outbound';
    from_phone_number: string | null;
    to_phone_number: string | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    timestamp: string;
  }
}

Phone call ended

phone_call.ended Triggered when a phone call ends. This event carries all end-of-call context — resolution status, who hung up, the resolved contact, the agent’s configured languages, the call summary, and the session’s custom_data (SIP X-headers + call metadata) — so listeners do not need a separate conversation.closed event for phone calls. For AI calls using the post-call workflow path, this event is sent after Call Finished workflows finish, so their updates to session custom data can be included. Timing and available fields vary by calling path; do not assume that every human-call event runs those workflows or contains a final summary. See Call lifecycle and outcomes.

Field	Description
`call_id`	The call record ID, when available.
`disposition`	Detailed result when available: `human_answered`, `no_answer`, `busy`, `declined`, `voicemail`, `failed`, `canceled`, or `unknown`. Use this to distinguish results grouped under `unanswered`.
`call_ended_by`	Who hung up: `user` (contact), `agent` (AI agent, including transfers), `system` (e.g. inactivity timeout), or `null` when unknown (e.g. outbound calls that never connected).
`ai_resolution_status`	Mirrors the persisted `chat_sessions.ai_closure_type`: `resolved` for completed calls, `handed_off` for transfers, or `null` for unanswered/failed calls.
`human_resolution_status`	Always `null` for phone calls — there is no human-resolve path on a call.
`contact_id`	The resolved contact’s id, or `null` if no contact was matched.
`contact`	Full contact record (id, name, email, phone, custom_data) when `contact_id` is set.
`language`	The phone agent’s configured language list (e.g. `["en"]`, `["es","en"]`), or `null` if no agent is attached.
`summary`	The summary stored on the session when the event is sent. It can be missing, empty, or preliminary if no final summary is available.
`custom_data`	The session’s `custom_data` jsonb after the post-call workflows: incoming SIP X-headers (with the `X-` prefix stripped), values from the `X-OPENCX-SESSION-CUSTOM-DATA` header, call metadata (`duration_seconds`, `participant_count`, `is_outbound`, `recording_available`, `agent_version`, `call_status`, optional `knowledge_snapshot`), plus whatever the `Call Finished` workflows merged in.

When custom_data.knowledge_snapshot is present, scoped snapshots include instruction_scope, knowledge_scope, and captured_at. For compatibility, the call-ended webhook also supplies top-level instruction_ids and directory_ids arrays inside the snapshot, defaulting missing arrays to []. Existing legacy arrays retain their values. These empty compatibility arrays do not mean the agent had no instructions; read the scope fields for configured selections. A scope with mode: "all" can have empty selection arrays. Scope selections do not identify which instructions were used during the call.

{
  event: 'phone_call.ended';
  organization_id: string;
  data: {
    session_id: string;
    phone_agent_id: string | null;   // null for human-only (direct-ring) calls
    phone_agent_name: string | null; // null for human-only (direct-ring) calls
    is_human_call: boolean;          // true when no AI agent was on the call
    direction: 'inbound' | 'outbound';
    from_phone_number: string | null;
    to_phone_number: string | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    timestamp: string;
    duration_seconds: number | null;
    outcome: 'completed' | 'unanswered' | 'transferred' | 'failed';
    call_id?: string;
    disposition?: 'human_answered' | 'no_answer' | 'busy' | 'declined' | 'voicemail' | 'failed' | 'canceled' | 'unknown';
    recording_url: string | null;
    summary: string | null;
    call_ended_by: 'user' | 'agent' | 'system' | null;
    ai_resolution_status: 'resolved' | 'handed_off' | 'assumed_resolved' | null;
    human_resolution_status: null;
    contact_id: string | null;
    language: string[] | null;
    custom_data: object | null;
  }
}

phone_call.transferred Triggered when the AI agent transfers a call to another destination (phone number, SIP URI, or graceful hangup).

{
  event: 'phone_call.transferred';
  organization_id: string;
  data: {
    session_id: string;
    phone_agent_id: string | null;   // null for human-only (direct-ring) calls
    phone_agent_name: string | null; // null for human-only (direct-ring) calls
    is_human_call: boolean;          // true when no AI agent was on the call
    direction: 'inbound' | 'outbound';
    from_phone_number: string | null;
    to_phone_number: string | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    timestamp: string;
    destination: {
      id: string;
      name: string;
      type: 'phone' | 'sip' | 'team' | 'hangup';
    };
    reason: string | null;
    // Present only when the transfer was triggered by the platform's automatic
    // failover on a non-recoverable mid-call error. Branch on presence only.
    failover?: {
      reason: 'provider_failure';
    };
  }
}

phone_call.failed Triggered when a phone call fails to connect. The failure_category field indicates the type of failure.

Category	Description
`no_answer`	Contact didn’t pick up
`rejected`	Call was actively rejected
`busy`	Line was busy
`trunk_error`	SIP trunk failure
`failed`	Generic failure (timeout, SIP error, etc.)

{
  event: 'phone_call.failed';
  organization_id: string;
  data: {
    session_id: string;
    phone_agent_id: string | null;   // null for human-only (direct-ring) calls
    phone_agent_name: string | null; // null for human-only (direct-ring) calls
    is_human_call: boolean;          // true when no AI agent was on the call
    direction: 'inbound' | 'outbound';
    from_phone_number: string | null;
    to_phone_number: string | null;
    contact?: {
      id: string;
      name?: string;
      email?: string;
      phone_number?: string;
      custom_data?: object;
    };
    timestamp: string;
    failure_reason: string;
    failure_category: 'no_answer' | 'rejected' | 'busy' | 'trunk_error' | 'failed';
  }
}

Email events

Email events cover broadcasts, sequences, session emails, and organization notifications sent through the existing tracked email paths from your verified sending domains. Each event is delivered only to webhook endpoints belonging to the sending organization. Configure subscriptions in Settings → Webhooks.

Event	When it occurs
`email.sent`	The email was sent; recipient-server delivery is not yet confirmed.
`email.delivered`	The recipient’s mail server accepted the email.
`email.delivery_delayed`	Delivery was temporarily delayed.
`email.opened`	An email open was detected. Requires open tracking on the sending domain.
`email.clicked`	A tracked link was clicked. Requires click tracking on the sending domain.
`email.bounced`	The email bounced as undeliverable.
`email.complained`	The recipient reported the email as spam.
`email.failed`	The email failed to send.
`email.suppressed`	A suppression rule blocked sending.
`email.scheduled`	The email was scheduled for future sending.

Only opens and clicks require their respective tracking settings. Subscribing to events does not enable tracking. An open detection is not proof that a person read the email. Events describe newly reported activity; subscribing does not replay historical events. Untagged emails and mail sent through other delivery integrations are outside this event stream. All 10 events use the same payload:

{
  event: 'email.clicked'; // One of the 10 event names above.
  organization_id: string;
  data: {
    email_id: string; // OpenCX tracking ID shared by events for this email.
    timestamp: string; // ISO 8601 time when the event occurred.
    from: string; // Sender email address.
    to: string[]; // Recipients reported for the email.
    subject: string;
    source: 'broadcast' | 'sequence' | 'session' | 'notification';
    source_id?: string; // Source reference when available; interpret with source.
    click_url?: string; // HTTP(S) URL, present only for a valid clicked link.
  };
}

Email bodies, attachments, device information, and internal routing metadata are not included. Delivery retries of the same incoming event use a stable idempotency key; separate opens and clicks remain separate events. Consumers should still deduplicate deliveries using the svix-id header and use data.timestamp because events may arrive out of order.

Overview

Blocklist

Autopilot

Organization

Contacts

Companies

Sessions

Connect

AI Phone Agents

Classical IVR

AI Email

AI WhatsApp

AI Actions

Sequences

Outbound Blocklist

Media

AI Training

Help Center

Resource Usage

Customer Insights

Teams

CSAT

Redaction

Crawl

Tags

Custom Statuses

Inbox Views

Office Hours

Handoff Analytics

SLA Analytics

Secrets

Audit Logs

Workflows (Beta)

Salesforce MIAW

Webhooks

Delivery, signatures & retries

Phone Call Events

Phone call ended

Email events

​Delivery, signatures & retries

​Phone Call Events

​Phone call ended

​Email events

Delivery, signatures & retries

Phone Call Events

Phone call ended

Email events