Custom Workflow Tools

Note: Solo's default workflows work automatically with no setup required. Custom workflow tools are only for advanced users who need full control over automation beyond what's available in their plan.

For extended workflow options based on your plan, reach out to sales. Custom workflow tools (such as n8n) are for users who need complete control over automation logic and integrations.

What are Custom Workflow Tools?

Custom workflow tools are external automation platforms that you can connect to Solo. Popular options include n8n (an open-source workflow automation tool), Zapier, Make, and others. With custom workflow tools, you can:

  • Build complex workflows: Multi-step automation
  • Integrate external services: Connect to any API
  • Full control: Complete control over automation logic
  • Reuse existing workflows: Use your existing workflows in your tool

Requirements

To use custom workflow tools, you need:

  • ✅ Your workflow tool instance: Self-hosted or cloud (e.g., n8n, Zapier, Make)
  • ✅ Webhook URL: Endpoint for Solo to send events
  • ✅ API Key: Generated in Solo Settings → API Keys
  • ✅ Understanding of your tool: Basic knowledge of your chosen workflow tool

Setup

Step 1: Set Up Your Workflow Tool

  1. Deploy your tool: Self-host or use cloud service (e.g., n8n, Zapier, Make)
  2. Configure webhooks: Set up webhook endpoint
  3. Test connection: Verify your tool is accessible
  4. Note webhook URL: You'll need this for Solo

Step 2: Enable Custom Workflows in Solo

  1. Go to Settings → Workflow
  2. Toggle "Use Custom Workflow Instance"
  3. Enter Webhook URL: Your workflow tool's webhook endpoint
  4. Enter API Key: Generate in Settings → API Keys
  5. Click "Save"

Step 3: Configure Your Workflow

  1. Create workflow in your tool (e.g., n8n)
  2. Add webhook trigger: Receives events from Solo
  3. Process events: Handle different event types
  4. Take actions: Send emails, create tasks, etc.
  5. Test workflow: Verify it works correctly

Important Notes

Default Workflows Disabled

When you enable custom workflow tools:

  • ❌ Solo's default workflows are disabled
  • ❌ Usage tracking may be limited
  • ✅ You handle all automation yourself
  • ✅ You're responsible for workflow reliability

Usage Tracking

With custom workflow tools:

  • Token usage: May not be tracked automatically
  • Agent executions: May not be tracked automatically
  • Manual tracking: You may need to track usage yourself
  • API available: Use /api/v1/usage/track to track usage

Webhook Events

Solo sends events to your workflow tool's webhook:

{
  "eventId": "uuid",
  "scope": "identity" | "business",
  "identityId": "uuid",
  "agent": {
    "id": "uuid",
    "kind": "inbox-manager",
    "name": "Jordan"
  },
  "type": "email" | "chat" | "task",
  "content": "...",
  "metadata": { ... }
}

See Webhook Events for complete details.

Workflow Examples

Example: n8n Workflow

Example 1: Email Auto-Reply

Trigger: Webhook receives email event

Steps:

  1. Check if auto-reply is appropriate
  2. Analyze email content
  3. Draft reply
  4. Send reply (or hold for approval)

Example 2: Task Creation

Trigger: Webhook receives actionable email

Steps:

  1. Extract task details
  2. Create task via Solo API
  3. Assign to appropriate agent
  4. Notify relevant parties

Example 3: External Integration

Trigger: Webhook receives any event

Steps:

  1. Process event
  2. Call external API (CRM, helpdesk, etc.)
  3. Update external system
  4. Return result to Solo

API Authentication

Using API Keys

Generate API keys in Settings → API Keys:

  1. Click "Generate API Key"
  2. Name the key (e.g., "Workflow Integration" or "n8n Workflows")
  3. Copy the key (shown only once)
  4. Use in your workflow tool: Authorization: Bearer <api-key>

Using Global API Key

If using Solo's internal workflow system:

  • Use the global API key from environment variables
  • Include identityId in query parameter or body
  • See API documentation for details

Best Practices

Start Simple

  • Begin with simple workflows
  • Test thoroughly before enabling
  • Add complexity gradually
  • Monitor for errors

Handle Errors

  • Set up error handling in your workflow tool
  • Log errors for debugging
  • Have fallback plans
  • Test error scenarios

Monitor Usage

  • Track token usage manually if needed
  • Monitor agent executions
  • Use /api/v1/usage/track endpoint
  • Stay within plan limits

Document Workflows

  • Document what each workflow does
  • Note dependencies and integrations
  • Keep configuration documented
  • Update when changes are made

Troubleshooting

Webhook 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

Workflow errors?

  • Check your workflow tool instance status
  • Verify workflow logic
  • Review error logs in your workflow tool
  • Test workflow manually

Authentication errors?

  • Verify API key is correct
  • Check key hasn't been revoked
  • Ensure Bearer prefix is used
  • Review API key permissions

Documentation

For tool-specific issues:

Next Steps

Version: 1.0
Last Updated: November 2025