Webhook API for Digital Human Events

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.

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)

warning_amber

The TIMEOUT_CONVERSATION event automatically triggers an END_CONVERSATION event. Your webhook will receive both notifications.

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:

code

{
  "headId": "yourHeadId",
  "webhookUrl": "https://example.com/webhooks/head-events",
  "startConversation": true,
  "endConversation": true,
  "timeoutConversation": true,
  "inactivityWarning": true
}

CURL Example:

code

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:

{ "sharedKey": "cbaab87d1cce6d79baad8e9e2607feb3"}

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.

warning_amber

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:

code

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/yourHeadId/enable-events?enableEvents=true' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken'

warning_amber

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

code

{
  "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

Extract the x-signature-256 header value from the incoming request
Compute the HMAC-SHA256 hash of the request body using your sharedKey
Compare your computed hash with the header value
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

code

curl -X 'GET' \
  'https://platform-api.unith.ai/head-events?headId=yourHeadId' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken'

Response Example

code

[
  {
    "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

code

{
  "headId": "yourHeadId",
  "webhookUrl": "https://example.com/webhooks/head-events",
  "startConversation": false,
  "endConversation": true,
  "timeoutConversation": true,
  "inactivityWarning": false
}

CURL Example

code

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:

code

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:

code

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

code

curl -X 'PUT' \
  'https://platform-api.unith.ai/head/yourHeadId/enable-events?enableEvents=false' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken'

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:

code

# 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.

scheduleLast updated Apr 9, 2026