Webhooks & Events

Overview

Sulus supports several server-side webhook events that are sent to your configured server URL. Here's a comprehensive overview of the webhook/server event system.

Sulus sends the following categories of webhook events to your server:

Call lifecycle events:

• call-started: Triggered when a call is initiated
• call-ended: Triggered when a call completes
• call-failed: Triggered when a call encounters an error

Speech events:

• speech-update: Real-time transcription updates
• transcript: Final transcription
• voice-input: User speaking detected

Assistant events:

• function-call: Tool/function invoked
• assistant-message: Assistant response
• conversation-update: Conversation state change

System events:

• error: Error occurred
• recording-ready: Call recording available
• analysis-ready: Call analysis complete

Chat events:

• chat.created: Triggered when a new chat conversation is initiated
• chat.deleted: Triggered when a chat conversation is deleted

Session events:

• session.created: Triggered when a new session is created
• session.updated: Triggered when a session is updated
• session.deleted: Triggered when a session is deleted

To receive webhook events, you configure a Server URL, an endpoint you expose to Sulus to receive conversation data in real-time. Unlike traditional webhooks, Sulus's server URLs can reply with meaningful responses (not just status codes), which is important for certain request types like assistant requests.

You can configure webhook events for chat and session events via your Assistant page in the Dashboard under "Server Messaging".

You can use a local forwarder to send webhooks to your local development server:

# Terminal 1: Create a public tunnel (e.g., with ngrok)
ngrok http 4242

# Terminal 2: Start the webhook listener
core-system listen --forward-to localhost:3000/webhook

The data flow is: Sulus > Tunnel URL > local listener (port 4242) > Your local server.

Note: the local listener is a forwarder only and does NOT create a public URL itself. You must use a separate tunneling service like ngrok and update your webhook URLs to point to the tunnel's public URL.

Here's a basic example of handling webhook events in Node.js/Express:

app.post('/api/webhook', async (req, res) => {
  const { type, call, timestamp } = req.body;

  switch (type) {
    case 'call-started':
      console.log(`Call ${call.id} started`);
      break;

    case 'speech-update':
      console.log(`User said: ${req.body.transcript}`);
      break;

    case 'function-call':
      const { functionName, parameters } = req.body.functionCall;
      const result = await processFunction(functionName, parameters);
      return res.json({ result });

    case 'call-ended':
      console.log(`Call ended. Duration: ${call.duration}s`);
      break;
  }

  res.status(200).send();
});

Your server should respond with the following HTTP status codes:

You can monitor webhook deliveries, check server response codes, and debug delivery failures via Observe > Webhook Logs in the Sulus dashboard.

In summary, Sulus's webhook system covers the full lifecycle of calls, chats, and sessions, and provides tooling (a local listener CLI, dashboard logs) to make development and debugging straightforward.