--- title: Webhook API for Digital Human Events slug: webhook-api-for-digital-human-events docTags: createdAt: 2026-01-19T12:04:49.576Z --- This guide explains how to configure and manage webhooks to receive real-time event notifications from your Digital Human interactions. ## Overview The Webhook API enables you to receive automated notifications when specific events occur during Digital Human sessions. When an event is triggered, the UNITH platform sends an HTTP POST request to your configured endpoint with event details. :::hint{type="info"} **Webhooks** allow you to integrate Digital Human events into your own systems, enabling custom workflows, analytics, and user tracking. ::: ## Requirements Before setting up webhooks, ensure you have: - An existing Digital Human (head\_id) - A publicly accessible server endpoint to receive webhook events - Valid authentication credentials (Bearer token) ## Available Event Types The platform currently supports four event types: | **Event Type** | **Description** | **Trigger Condition** | | ---------------------- | -------------------------- | ------------------------------------------------------------------------------ | | `START_CONVERSATION` | User initiates interaction | First message or interaction with Digital Human | | `END_CONVERSATION` | Session ends | WebSocket closes or browser window closes | | `INACTIVITY_WARNING` | Inactivity detected | User inactive for configured duration (warning popup displayed) | | `TIMEOUT_CONVERSATION` | Session timeout | Maximum inactivity duration reached (automatically triggers END\_CONVERSATION) | :::hint{type="warning"} The **TIMEOUT\_CONVERSATION** event automatically triggers an **END\_CONVERSATION** event. Your webhook will receive both notifications. ::: :::hint{type="info"} **START\_CONVERSATION** event is triggered upon first user message sent towards the digital human. ::: ## Step 1: Configure Webhook Endpoint Use the `/head-events` endpoint to register your webhook URL and specify which events you want to receive. **Endpoint:** `POST https://platform-api.unith.ai/head-events` **Request Body:** ```json { "headId": "yourHeadId", "webhookUrl": "https://example.com/webhooks/head-events", "startConversation": true, "endConversation": true, "timeoutConversation": true, "inactivityWarning": true } ``` **CURL Example:** ```curl curl -X 'POST' \ 'https://platform-api.unith.ai/head-events' \ -H 'accept: application/json' \ -H 'Authorization: Bearer yourBearerToken' \ -H 'Content-Type: application/json' \ -d '{ "headId": "yourHeadId", "webhookUrl": "https://example.com/webhooks/head-events", "startConversation": true, "endConversation": true, "timeoutConversation": true, "inactivityWarning": true }' ``` **Response** The API returns a shared secret key used for webhook signature verification: :::BlockQuote \{ "sharedKey": "cbaab87d1cce6d79baad8e9e2607feb3"} ::: :::hint{type="info"} All event types are **optional**. By default, events are disabled and are only enabled when explicitly included in the request with a value of `true`. ::: :::hint{type="warning"} Store the sharedKey **securely**. You will need it to verify the authenticity of incoming webhook requests. ::: ## Step 2: Enable Webhook Events for Your Digital Human After configuring your webhook, you must enable event notifications for your specific Digital Human. **Endpoint:** `PUT https://platform-api.unith.ai/head/{headId}/enable-events` **Query Parameter** | **Parameter** | **Required** | **Description** | | ------------- | ------------ | --------------------------------------------- | | enableEvents | Yes | Set to true to activate webhook notifications | **CURL Example:** ```curl curl -X 'PUT' \ 'https://platform-api.unith.ai/head/yourHeadId/enable-events?enableEvents=true' \ -H 'accept: application/json' \ -H 'Authorization: Bearer yourBearerToken' ``` :::hint{type="warning"} All Digital Humans have enableEvents set to **false** by default. You must explicitly enable events after webhook configuration. ::: ## Step 3: Receive Webhook Events Once configured and enabled, the UNITH platform will send HTTP POST requests to your webhook URL whenever subscribed events occur. **Webhook Payload Example** ```json { "timestamp": "2026-01-15T09:57:33Z", "head_id": "8eab5b23-024a-45cb-a0e1-9d3ffd6c9610", "session_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "public_head_id": "jane-15326", "public_org_id": "acme", "event_type": "start_conversation" } ``` **Payload Fields** | **Field** | **Type** | **Description** | | ---------------- | -------- | ------------------------------------------------------------------------------------------------- | | `timestamp` | string | ISO 8601 timestamp when the event occurred | | `head_id` | string | Internal UUID of the Digital Human | | `session_id` | string | Unique session identifier | | `public_head_id` | string | Public-facing Digital Human identifier | | `public_org_id` | string | Public-facing organization identifier | | `event_type` | string | Event type: `start_conversation, end_conversation, inactivity_warning`, or `timeout_conversation` | ## Webhook Security: Signature Verification Every webhook request includes an `x-signature-256` header containing an HMAC-SHA256 signature. Use this to verify that requests genuinely come from UNITH. **Verification Process** 1. Extract the `x-signature-256` header value from the incoming request 2. Compute the HMAC-SHA256 hash of the request body using your `sharedKey` 3. Compare your computed hash with the header value 4. Accept the webhook only if they match ## Managing Webhook Configurations ### Retrieve Webhook Configuration To view the current webhook configuration for a specific Digital Human: **Endpoint:** `GET https://platform-api.unith.ai/head-events` **Query Parameter** | **Parameter** | **Required** | **Description** | | ------------- | ------------ | --------------------- | | headId | Yes | Your Digital Human ID | **CURL Example** ```curl curl -X 'GET' \ 'https://platform-api.unith.ai/head-events?headId=yourHeadId' \ -H 'accept: application/json' \ -H 'Authorization: Bearer yourBearerToken' ``` **Response Example** ```javascript [ { "id": 4, "createdAt": "2026-01-16T09:56:12.076Z", "updatedAt": "2026-01-16T09:56:12.076Z", "orgId": "3f7627db-6f87-4510-85a8-993518add9c7", "headId": "8eab5b23-024a-45cb-a0e1-9d3ffd6c9610", "webhookUrl": "https://example.com/webhooks/head-events", "sharedKey": "cbaab87d1cce6d79baad8e9e2607feb3", "startConversation": true, "endConversation": true, "timeoutConversation": true, "inactivityWarning": true } ] ``` ### Update Event Subscriptions To modify which events trigger webhook notifications: **Endpoint:** `PATCH https://platform-api.unith.ai/head-events/{webhookId}` **Request Body** ```json { "headId": "yourHeadId", "webhookUrl": "https://example.com/webhooks/head-events", "startConversation": false, "endConversation": true, "timeoutConversation": true, "inactivityWarning": false } ``` **CURL Example** ```curl curl -X 'PATCH' \ 'https://platform.api.unith.ai/head-events/yourWebhookId' \ -H 'accept: application/json' \ -H 'Authorization: Bearer yourBearerToken' \ -H 'Content-Type: application/json' \ -d '{ "headId": "yourHeadId", "webhookUrl": "https://example.com/webhooks/head-events", "startConversation": false, "endConversation": true, "timeoutConversation": true, "inactivityWarning": false }' ``` ### Retrieve Specific Webhook Details To view details of a specific webhook configuration: **Endpoint:** `GET https://platform-api.unith.ai/head-events/{webhookId}` **CURL Example:** ```curl curl -X 'GET' \ 'https://platform-api.unith.ai/head-events/yourWebhookId' \ -H 'accept: application/json' \ -H 'Authorization: Bearer yourBearerToken' ``` ### Delete Webhook Configuration To permanently remove a webhook: **Endpoint:** `DELETE https://platform-api.unith.ai/head-events/{webhookId}` **CURL Example:** ```curl curl -X 'DELETE' \ 'https://platform-api.unith.ai/head-events/yourWebhookId' \ -H 'accept: */*' \ -H 'Authorization: Bearer yourBearerToken' ``` ### Temporarily Disable Webhooks To preserve your webhook configuration but stop receiving events, disable event notifications: **Endpoint:** `PUT https://platform-api.unith.ai/head/{headId}/enable-events` **CURL Example** ```curl curl -X 'PUT' \ 'https://platform-api.unith.ai/head/yourHeadId/enable-events?enableEvents=false' \ -H 'accept: application/json' \ -H 'Authorization: Bearer yourBearerToken' ``` :::hint{type="info"} Setting **enableEvents=false** stops event delivery without deleting your webhook configuration. Re-enable by setting it back to true. ::: *** ## Complete Workflow Example This example demonstrates the full webhook setup process: ```bash # Step 1: Configure webhook and capture the shared key SHARED_KEY=$(curl -s -X 'POST' \ 'https://platform-api.unith.ai/head-events' \ -H 'accept: application/json' \ -H 'Authorization: Bearer yourBearerToken' \ -H 'Content-Type: application/json' \ -d '{ "headId": "yourHeadId", "webhookUrl": "https://example.com/webhooks/head-events", "startConversation": true, "endConversation": true, "timeoutConversation": true, "inactivityWarning": true }' | jq -r '.sharedKey') # Step 2: Enable events for your Digital Human curl -X 'PUT' \ 'https://platform-api.unith.ai/head/yourHeadId/enable-events?enableEvents=true' \ -H 'accept: application/json' \ -H 'Authorization: Bearer yourBearerToken' # Step 3: Verify webhook configuration curl -X 'GET' \ 'https://platform-api.unith.ai/head-events?headId=yourHeadId' \ -H 'accept: application/json' \ -H 'Authorization: Bearer yourBearerToken' ``` ## Important Notes **Authentication:** All API endpoints require a valid Bearer token in the Authorization header. **Webhook Response Time:** Your webhook endpoint should respond within 5 seconds to avoid timeout errors. **Retry Logic:** If your endpoint returns an error or times out, the platform will retry delivery up to 3 times with exponential backoff. **HTTPS Required:** Webhook URLs must use HTTPS for security. HTTP endpoints are not supported. **Event Order:** Events are delivered in the order they occur, but network conditions may cause occasional delays. **Shared Key Storage:** Store the sharedKey securely and never expose it in client-side code or public repositories.