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 true 220,220,221left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type streaming mode limitation only start conversation and end conversation events are currently supported in streaming mode , which is the default for new digital humans inactivity warning and timeout conversation events are currently not available in streaming mode the timeout conversation event automatically triggers an end conversation event your webhook will receive both notifications 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 { "headid" "yourheadid", "webhookurl" "https //example com/webhooks/head events", "startconversation" true, "endconversation" true, "timeoutconversation" true, "inactivitywarning" true } curl example 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"} 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 //platform api unith ai/head/{headid}/enable events query parameter true 220,220,221left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type curl example curl x 'put' \\ 'https //platform api unith ai/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 true 220,220,221left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type 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 true 220,220,221left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type left unhandled content type curl example curl x 'get' \\ 'https //platform api unith ai/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 //platform api unith ai/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 //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 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 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 x 'put' \\ 'https //platform api unith ai/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 //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