Session Lifecycle Events: Complete Technical Guide
This article provides a comprehensive overview of Session Lifecycle and Function Execution events in the Darwin ecosystem. These events enable developers to build real-time integrations, trigger external workflows, and perform deep data analysis based on session behavior.
1. Session Lifecycle Events
These events allow you to track a conversation's status from the moment it is initiated until it is archived or transitioned.
session.opened: Triggered the instant a new session begins.session.closed: Triggered when a session ends, typically due to user inactivity.session.closed.unforwarded: Specifically triggered when a session closes without ever being transferred to a human agent or an external flow.session.analyzed: Triggered after the AI processes the interaction, calculates smart fields, and generates the conversation summary.session.stage.transitioned: Triggered when a session moves between defined pipeline stages (e.g., Lead to Qualified).session.*: A wildcard to subscribe to all session lifecycle and transfer events simultaneously.
Session Transfer Events
session.forwarded: A generic event triggered whenever a session is transferred for any reason.session.forwarded.qualified: Triggered when a session is transferred because it met specific qualification criteria.session.forwarded.escalated: Triggered when a session is moved through an escalation path (e.g., from bot to manager).session.forwarded.recovered: Triggered when a session is transferred as part of a recovery flow.
2. Function Execution Events
These events monitor when the AI engine invokes specific tools or external logic.
function.call.<functionName>: Triggered when a specific named function is executed.function.call.*: Wildcard to subscribe to all function call executions.function.*: Wildcard for all events related to function logic.
3. Webhook Payload Structure
All Darwin webhooks follow a standardized structure to ensure consistency across different event types.
Common Properties
Property | Description |
| The specific event type (e.g., |
| The exact time the event occurred. |
| The unique ID of the agent associated with the event. |
| The name of the agent. |
| An object containing specific details related to the event type. |
Data Object Details
The data object provides deep context depending on the event:
For Sessions: Includes
sessionId,channelName,conversationTitle,summary,smartFields, and activity timestamps (lastHumanActivityAt).For Functions: Includes
inputs(arguments sent to the function),functionStatus,functionCallId, andappmetadata.
4. Security & Payload Integrity
To ensure that webhooks originate from Darwin and have not been tampered with, every request includes a cryptographic signature.
Mechanism: HMAC-SHA256.
Header:
X-SIGNATURE.
Implementation Example (Node.js)
To verify the payload, compute the HMAC-SHA256 hash of the raw request body using your Webhook Secret and compare it to the header value:
JavaScript
const crypto = require('crypto'); // Ensure you use the raw request body const payload = JSON.stringify(request.body); const secret = 'your_app_secret'; const receivedSignature = request.headers['x-signature']; const expectedSignature = crypto.createHmac('sha256', secret) .update(payload) .digest('hex'); if (receivedSignature !== expectedSignature) { throw new Error('Invalid signature: Payload authenticity could not be verified.'); } // Proceed with your logic