Webhooks

Solo can send webhook events to your endpoints when certain events occur. Configure webhooks to receive real-time notifications.

What are Webhooks?

Webhooks are HTTP callbacks that Solo sends to your endpoint when events occur:

  • Real-time: Receive events as they happen
  • Automatic: No polling required
  • Configurable: Choose which events to receive
  • Secure: Signed requests for verification

Webhook Events

Available Events

Solo can send webhooks for:

  • Email received: When email arrives at your Solo Identity
  • Agent execution: When agents execute actions
  • Task created: When tasks are created
  • Conversation updated: When conversations change
  • Identity updated: When identity settings change

Event Format

Webhook events are sent as JSON:

{
  "event": "email.received",
  "timestamp": "2025-01-01T00:00:00Z",
  "data": {
    "identityId": "identity-id",
    "emailId": "email-id",
    "from": "sender@example.com",
    "subject": "Email Subject",
    "body": "Email body content"
  }
}

Setting Up Webhooks

Configure Webhook URL

  1. Go to Settings → Workflow
  2. Enable Custom Workflows (if using custom workflow tools)
  3. Enter Webhook URL: Your endpoint URL
  4. Save configuration

Webhook Endpoint Requirements

Your webhook endpoint must:

  • Accept POST requests: Receive POST with JSON body
  • Return 200 OK: Respond with success status
  • Handle quickly: Respond within 5 seconds
  • Be accessible: Publicly accessible URL

Webhook Security

Signature Verification

Solo signs webhook requests for verification:

  • Signature header: X-Solo-Signature
  • Timestamp header: X-Solo-Timestamp
  • Verify signature: Validate request authenticity

Verification Process

  1. Extract signature: Get signature from header
  2. Get timestamp: Get timestamp from header
  3. Recreate signature: Sign request body with your secret
  4. Compare signatures: Verify they match

Example Verification

const crypto = require('crypto')

function verifyWebhook(body, signature, timestamp, secret) {
  const payload = `${timestamp}.${body}`
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )
}

Webhook Payloads

Email Received

{
  "event": "email.received",
  "timestamp": "2025-01-01T00:00:00Z",
  "data": {
    "identityId": "identity-id",
    "emailId": "email-id",
    "from": "sender@example.com",
    "to": "yourname@solomail.io",
    "subject": "Email Subject",
    "body": "Email body content",
    "attachments": []
  }
}

Agent Execution

{
  "event": "agent.execution",
  "timestamp": "2025-01-01T00:00:00Z",
  "data": {
    "identityId": "identity-id",
    "agentId": "agent-id",
    "status": "completed",
    "operation": "send_email",
    "result": {
      "success": true
    }
  }
}

Task Created

{
  "event": "task.created",
  "timestamp": "2025-01-01T00:00:00Z",
  "data": {
    "identityId": "identity-id",
    "taskId": "task-id",
    "title": "Task Title",
    "description": "Task description",
    "priority": "high"
  }
}

Handling Webhooks

Best Practices

  • Idempotency: Handle duplicate events gracefully
  • Async processing: Process events asynchronously
  • Error handling: Handle errors gracefully
  • Logging: Log all webhook events
  • Retries: Implement retry logic for failures

Response Format

Your endpoint should return:

Success:

{
  "success": true
}

Error:

{
  "success": false,
  "error": "Error message"
}

Testing Webhooks

Test Endpoint

Use a test endpoint to verify webhooks:

  • Webhook.site: Test webhook endpoint
  • ngrok: Expose local endpoint
  • RequestBin: Temporary webhook endpoint

Testing Process

  1. Set up test endpoint: Use webhook testing service
  2. Configure webhook: Point to test endpoint
  3. Trigger event: Cause event to occur
  4. Verify payload: Check received payload
  5. Test production: Move to production endpoint

Troubleshooting

Webhooks not received?

  • Check webhook URL is correct
  • Verify endpoint is publicly accessible
  • Check endpoint returns 200 OK
  • Review webhook logs

Invalid signature?

  • Verify signature verification logic
  • Check secret key is correct
  • Ensure timestamp is included
  • Review signature format

Duplicate events?

  • Implement idempotency checks
  • Use event IDs to deduplicate
  • Store processed event IDs
  • Handle retries gracefully

Next Steps

Version: 1.0
Last Updated: November 2025