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 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 session duration reached (automatically triggers end conversation) the timeout conversation event automatically triggers an end conversation event your webhook will receive both notifications 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 //production api unith live/head events request body { "headid" "yourheadid", "webhookurl" "https //example com/webhooks/head events", "startconversation" true, "endconversation" true, "timeoutconversation" true, "inactivitywarning" true } curl example curl x 'post' \\ 'https //production api unith live/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"} 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 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 //production api unith live/head/{headid}/enable events query parameter parameter required description enableevents yes set to true to activate webhook notifications curl example curl x 'put' \\ 'https //production api unith live/head/yourheadid/enable events?enableevents=true' \\ h 'accept application/json' \\ h 'authorization bearer yourbearertoken' 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 { "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 //production api unith live/head events query parameter parameter required description headid yes your digital human id curl example curl x 'get' \\ 'https //production api unith live/head events?headid=yourheadid' \\ h 'accept application/json' \\ h 'authorization bearer yourbearertoken' response example \[ { "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 //production api unith live/head events/{webhookid} request body { "headid" "yourheadid", "webhookurl" "https //example com/webhooks/head events", "startconversation" false, "endconversation" true, "timeoutconversation" true, "inactivitywarning" false } curl example curl x 'patch' \\ 'https //production api unith live/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 //production api unith live/head events/{webhookid} curl example curl x 'get' \\ 'https //production api unith live/head events/yourwebhookid' \\ h 'accept application/json' \\ h 'authorization bearer yourbearertoken' delete webhook configuration to permanently remove a webhook endpoint delete https //production api unith live/head events/{webhookid} curl example curl x 'delete' \\ 'https //production api unith live/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 //production api unith live/head/{headid}/enable events curl example curl x 'put' \\ 'https //production api unith live/head/yourheadid/enable events?enableevents=false' \\ h 'accept application/json' \\ h 'authorization bearer yourbearertoken' 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 \# step 1 configure webhook and capture the shared key shared key=$(curl s x 'post' \\ 'https //production api unith live/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 //production api unith live/head/yourheadid/enable events?enableevents=true' \\ h 'accept application/json' \\ h 'authorization bearer yourbearertoken' \# step 3 verify webhook configuration curl x 'get' \\ 'https //production api unith live/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