Webhooks & Events

Event Model

Every service on Ergon emits events when meaningful actions occur. Events are the foundation for automations, real-time streaming, and webhook delivery — anything that needs to react to change originates from an event.

Naming Convention

Event types follow the pattern {service}.{entity}.{action}. This makes it straightforward to filter by service, entity, or specific action. Some examples:

• workflows.items.created — a new item was added to a workflow
• channels.message.dispatched — a message was dispatched through a channel
• conversations.message.added — a message was added to a conversation
• buckets.files.processed — a file finished processing

Event Envelope

Every event is wrapped in a standard envelope that carries metadata alongside the entity-specific payload. The envelope includes the event type, the originating service, the company scope, actor information describing who or what triggered the event, a timestamp, and the payload itself.

{
  "event_id": "evt_9f2a1b3c4d5e",
  "event_type": "workflows.items.created",
  "source": "workflows",
  "company_id": "comp_abc123",
  "actor_id": "usr_def456",
  "actor_type": "user",
  "timestamp": "2026-04-12T14:30:00Z",
  "payload": {
    "item_id": "item_789ghi",
    "workflow_id": "wf_012jkl",
    "phase_id": "phase_345mno",
    "title": "New support request",
    "field_values": {
      "priority": "high",
      "category": "billing"
    }
  }
}

Event Streams

The Event Streams service acts as a centralized event store for the entire platform. It consumes events from all services and persists them in a queryable database. This gives you a unified view of everything that happens across your organization.

At ingest, each event is projected to a metadata-only record — the envelope fields and lightweight identifiers are stored, but large or sensitive payload content (for example, message bodies or field values) is not persisted. Use Event Streams for audit, search, and observability; fetch the full entity from its owning service when you need its complete contents.

Querying Events

The Event Streams API lets you query stored events with filters for source service, event type, actor, correlation ID, and time range. This is useful for building audit trails, debugging cross-service flows, and powering activity dashboards.

Metrics & Traces

Event Streams provides built-in metrics — total event counts, event rates, timeseries breakdowns by granularity (hour, day, week), top event types, top actors, and per-source distributions. The traces endpoint groups events by correlation_id to visualize cross-service flows as distributed traces, showing how a single user action cascades through multiple services.

WebSocket Connections

For scenarios that require real-time updates — such as streaming agent responses or watching a file being processed — the platform exposes WebSocket endpoints. These provide a persistent, low-latency connection that pushes events to your client as they happen.

Authentication

WebSocket connections authenticate via a token query parameter. Pass the same bearer token you use for REST API calls.

Available Streams

The following WebSocket endpoints are available:

• /api/v1/conversations/ws/conversations/{id}/stream — stream conversation messages as they are generated
• /api/v1/workflows/ws/workflows/{id}/live — live updates for a workflow (item moves, field changes, new items)
• /api/v1/workflows/ws/companies/{id}/live — company-wide workflow events
• /api/v1/buckets/ws/files/{id}/live — file processing status updates
• /api/v1/buckets/ws/buckets/{id}/live — bucket-level file activity
• /api/v1/worksheets/ws/worksheets/{id}/live — worksheet collaboration updates
• /api/v1/worksheets/ws/folders/{id}/live — folder-level worksheet events
• /api/v1/event-streams/ws/companies/{id}/live — centralized company-wide event stream

# Stream conversation messages
wscat -c "wss://platform.ergondata.ai/api/v1/conversations/ws/conversations/{conversation_id}/stream?token={your_token}"

# Watch workflow item updates
wscat -c "wss://platform.ergondata.ai/api/v1/workflows/ws/workflows/{workflow_id}/live?token={your_token}"

# Monitor file processing
wscat -c "wss://platform.ergondata.ai/api/v1/buckets/ws/files/{file_id}/live?token={your_token}"

Payload Format

All event payloads are JSON. Every payload is wrapped in the standard event envelope described above, and the payload field carries entity-specific data. Below are representative examples for common events.

Workflow Item Created

{
  "event_id": "evt_a1b2c3d4e5f6",
  "event_type": "workflows.items.created",
  "source": "workflows",
  "company_id": "comp_abc123",
  "actor_id": "usr_def456",
  "actor_type": "user",
  "timestamp": "2026-04-12T14:30:00Z",
  "payload": {
    "item_id": "item_789ghi",
    "workflow_id": "wf_012jkl",
    "phase_id": "phase_345mno",
    "title": "New support request",
    "assigned_to": null,
    "field_values": {
      "priority": "high",
      "category": "billing"
    }
  }
}

Channel Message Received

{
  "event_id": "evt_f6e5d4c3b2a1",
  "event_type": "channels.email.received",
  "source": "channels",
  "company_id": "comp_abc123",
  "actor_id": "svc_channels",
  "actor_type": "service",
  "timestamp": "2026-04-12T15:05:22Z",
  "payload": {
    "message_id": "msg_xyz789",
    "address_id": "addr_qrs456",
    "channel_type": "email",
    "from": "[email protected]",
    "subject": "Password reset not working",
    "body": "I tried resetting my password but the link expired..."
  }
}

File Processing Completed

{
  "event_id": "evt_1a2b3c4d5e6f",
  "event_type": "buckets.files.processed",
  "source": "buckets",
  "company_id": "comp_abc123",
  "actor_id": "svc_buckets",
  "actor_type": "service",
  "timestamp": "2026-04-12T15:12:47Z",
  "payload": {
    "file_id": "doc_uvw123",
    "bucket_id": "fld_mno456",
    "filename": "quarterly-report.pdf",
    "status": "completed",
    "page_count": 24,
    "chunk_count": 87
  }
}

The envelope fields — event_id, event_type, source, company_id, actor_id, actor_type, and timestamp — are consistent across all event types. Automation rules in the central Automations service evaluate against these fields, so you can build filters like “only fire when the actor is a service account” or “only for events from the workflows service.”