Webhook Events

When using custom workflow tools (such as n8n), Solo sends events to your webhook endpoint. This document describes the event structure and types.

Event Structure

All events follow this structure:

{
  "eventId": "uuid",
  "scope": "identity" | "business",
  "identityId": "uuid",
  "agent": {
    "id": "uuid",
    "kind": "inbox-manager",
    "name": "Jordan"
  },
  "type": "email" | "chat" | "task" | "agent" | "system",
  "visibility": "visible" | "silent" | "internal",
  "conversationId": "uuid",
  "content": "...",
  "metadata": { ... },
  "createdAt": "2025-01-15T10:30:00Z"
}

Event Fields

eventId

  • Type: UUID string
  • Description: Unique identifier for this event
  • Use: Deduplication, tracking

scope

  • Type: "identity" | "business"
  • Description: Scope of the event
  • Use: Routing, permissions

identityId

  • Type: UUID string
  • Description: Solo Identity that owns this event
  • Use: Identity-scoped processing

agent

  • Type: Object
  • Description: Agent that generated this event
  • Fields:
    • id: Agent UUID
    • kind: Agent type (e.g., "inbox-manager")
    • name: Agent display name

type

  • Type: String
  • Description: Type of event
  • Values: "email", "chat", "task", "agent", "system"

visibility

  • Type: String
  • Description: Who can see this event
  • Values:
    • "visible": Customer-facing
    • "silent": No thread message
    • "internal": Agent coordination only

conversationId

  • Type: UUID string (optional)
  • Description: Conversation this event belongs to
  • Use: Threading, context

content

  • Type: String
  • Description: Event content (email body, message, etc.)
  • Use: Processing, analysis

metadata

  • Type: Object
  • Description: Additional event data
  • Use: Context, routing, processing

createdAt

  • Type: ISO 8601 timestamp
  • Description: When the event occurred
  • Use: Ordering, timing

Event Types

Email Events

Type: "email"

Metadata:

{
  "emailData": {
    "subject": "Meeting Request",
    "body": "...",
    "from": "sender@example.com",
    "to": ["recipient@solomail.io"],
    "headers": { ... }
  },
  "routing": {
    "source": "email",
    "roleId": "inbox-manager"
  }
}

Common Events:

  • New email received
  • Email replied to
  • Email forwarded
  • Attachment received

Task Events

Type: "task"

Metadata:

{
  "taskData": {
    "title": "Follow up with customer",
    "status": "pending",
    "intent": "INQUIRY"
  },
  "routing": {
    "source": "email",
    "roleId": "inbox-manager"
  }
}

Common Events:

  • Task created
  • Task updated
  • Task completed
  • Task assigned

Chat Events

Type: "chat"

Metadata:

{
  "chatData": {
    "channel": "slack",
    "message": "...",
    "thread": "uuid"
  }
}

Common Events:

  • New message
  • Message replied to
  • Thread updated

Agent Events

Type: "agent"

Metadata:

{
  "agentData": {
    "action": "email.reply",
    "decision": "send",
    "confidence": 0.85
  }
}

Common Events:

  • Agent action taken
  • Agent decision made
  • Agent escalation
  • Agent error

System Events

Type: "system"

Metadata:

{
  "systemData": {
    "event": "identity.activated",
    "data": { ... }
  }
}

Common Events:

  • Identity activated
  • Agent created
  • Configuration changed
  • System notifications

Processing Events

In Your Workflow Tool (e.g., n8n)

  1. Receive webhook: Your workflow tool receives event
  2. Parse event: Extract event data
  3. Route by type: Handle different event types
  4. Process: Take appropriate action
  5. Respond: Return result (if needed)

Example Workflow

Webhook Trigger
  ↓
Switch (by event.type)
  ├─ email → Email Handler
  ├─ task → Task Handler
  ├─ chat → Chat Handler
  └─ agent → Agent Handler

Best Practices

Handle All Event Types

  • Set up handlers for all event types
  • Use switch/if logic to route
  • Have default handler for unknown types

Validate Events

  • Check required fields
  • Verify event structure
  • Validate identityId matches
  • Check event signatures (if using)

Idempotency

  • Use eventId for deduplication
  • Store processed eventIds
  • Skip duplicate events
  • Handle retries gracefully

Error Handling

  • Log errors for debugging
  • Return appropriate status codes
  • Don't crash on invalid events
  • Have fallback handling

Security

Authentication

  • Use API keys for authentication
  • Verify webhook signatures (if available)
  • Validate identityId matches your identity
  • Check scope permissions

Rate Limiting

  • Implement rate limiting
  • Handle burst traffic
  • Monitor for abuse
  • Set appropriate limits

Troubleshooting

Not receiving events?

  • Check webhook URL is correct
  • Verify your workflow tool instance is accessible
  • Check API key is valid
  • Review Solo logs for errors

Events not processing?

  • Check event structure matches
  • Verify event type handling
  • Review error logs
  • Test with sample events

Duplicate events?

  • Implement idempotency
  • Store processed eventIds
  • Check for retries
  • Handle gracefully

Next Steps

Version: 1.0
Last Updated: November 2025