Event types

Subscribe to one or more of these event types when registering an endpoint. Pass an empty events array to subscribe to all.

Common envelope

Every delivery shares the same outer shape:

{
  "event": "synthesis.completed",
  "workspace_id": "ws_...",
  "timestamp": "2026-04-24T18:30:00Z",
  "data": { /* event-specific */ }
}

And these headers:

Header	Value
`X-Ontora-Event`	The event type (e.g., `synthesis.completed`)
`X-Ontora-Delivery-Id`	A UUID for this delivery attempt
`X-Ontora-Signature`	`sha256=<hmac>` — see Signing & verification
`Content-Type`	`application/json`

Events

`campaign.started`

Fires when a campaign transitions from draft to active.

{
  "event": "campaign.started",
  "workspace_id": "ws_...",
  "timestamp": "2026-04-24T18:30:00Z",
  "data": {
    "interview_id": "iv_...",
    "name": "Q2 facility-ops interviews",
    "contact_count": 24
  }
}

`campaign.paused`

Fires when a campaign is paused.

{
  "event": "campaign.paused",
  "workspace_id": "ws_...",
  "timestamp": "2026-04-24T18:30:00Z",
  "data": {
    "interview_id": "iv_...",
    "reason": "user_paused"
  }
}

`campaign.completed`

Fires when every contact’s conversation reaches completed. Synthesis usually starts immediately after.

{
  "event": "campaign.completed",
  "workspace_id": "ws_...",
  "timestamp": "2026-04-24T18:30:00Z",
  "data": {
    "interview_id": "iv_...",
    "completed_count": 24,
    "total_count": 24
  }
}

`interview.scheduled`

Fires when a contact’s interview is booked or first invited.

{
  "event": "interview.scheduled",
  "workspace_id": "ws_...",
  "timestamp": "2026-04-24T18:30:00Z",
  "data": {
    "interview_id": "iv_...",
    "conversation_id": "cv_...",
    "contact": {
      "name": "Sam Rivera",
      "email": "sam@example.com"
    },
    "scheduled_for": "2026-04-25T15:00:00Z"
  }
}

`interview.completed`

Fires when a single conversation finishes. Transcript is available via the export endpoints.

{
  "event": "interview.completed",
  "workspace_id": "ws_...",
  "timestamp": "2026-04-24T18:30:00Z",
  "data": {
    "interview_id": "iv_...",
    "conversation_id": "cv_...",
    "contact": {
      "name": "Sam Rivera",
      "email": "sam@example.com"
    },
    "duration_minutes": 27
  }
}

`synthesis.completed`

Fires when the synthesis pipeline finishes for a campaign. The cartography, roadmap, and personas are all queryable now.

{
  "event": "synthesis.completed",
  "workspace_id": "ws_...",
  "timestamp": "2026-04-24T18:30:00Z",
  "data": {
    "interview_id": "iv_...",
    "outputs": ["cartography", "roadmap", "personas"]
  }
}

This is usually the most useful event — most consumers register only for synthesis.completed and pull the report via GET /v1/interviews/{id}/export/report.

Get started

Core concepts

Guides

MCP server

CLI

Webhooks

Common envelope

Events

`campaign.started`

`campaign.paused`

`campaign.completed`

`interview.scheduled`

`interview.completed`

`synthesis.completed`

​Common envelope

​Events

​campaign.started

​campaign.paused

​campaign.completed

​interview.scheduled

​interview.completed

​synthesis.completed

Common envelope

Events

`campaign.started`

`campaign.paused`

`campaign.completed`

`interview.scheduled`

`interview.completed`

`synthesis.completed`