Webhooks and Callbacks

Tavus sends JSON payloads to the callback_url you configure on each resource. On your server, read the body and branch on event_type (and message_type where noted). This page covers five callback areas: conversation events (below), guardrails, objectives, face training, and video generation - payload shapes differ, and most event-specific fields live under properties.

Signed callbacks

Set callback_secret alongside a PAL/persona or conversation callback_url to authenticate its conversation callbacks. Tavus adds an X-Tavus-Signature header containing the lowercase hexadecimal HMAC-SHA256 digest of the exact HTTP request body bytes, using your shared secret encoded as UTF-8. This field applies to conversation callbacks, with optional defaults saved on the PAL/persona. Configure LLM tool callbacks separately through their delivery.api.auth settings; legacy guardrail and objective callback settings do not use this field. Secrets must be nonempty strings of at most 256 UTF-8 bytes. They are write-only and are not returned in resource GET or list responses. Omitting a secret on a conversation with no signing default keeps the existing unsigned payload and headers. Signing adds a header without changing the JSON payload shape.

PAL defaults and conversation overrides

Save a default URL and secret together on Create PAL:

{
  "pal_name": "Support assistant",
  "system_prompt": "Help customers with their support questions.",
  "default_face_id": "rc9cff32ceba",
  "callback_url": "https://yourwebsite.com/webhooks/pal",
  "callback_secret": "your-shared-secret"
}

A conversation that omits its callback fields inherits the PAL’s URL and signing secret. An empty conversation callback_url also inherits the defaults.

To change only the signing secret for one conversation, supply callback_secret and keep the PAL’s default URL.
To override the URL, supply a conversation callback_url (or its webhook_url alias). Supply a callback_secret with that override to sign its callbacks. An explicit URL without a secret receives unsigned callbacks; the PAL’s secret is not forwarded to the override endpoint.
Without a URL or signing secret at either level, behavior remains unchanged.

For example, sign one conversation’s callbacks at a different endpoint:

{
  "pal_id": "pcb7a34da5fe",
  "callback_url": "https://yourwebsite.com/webhooks/conversation",
  "callback_secret": "another-shared-secret"
}

Each conversation saves the selected URL and signing configuration when it is created. Changing the PAL’s defaults affects future conversations. These rules also apply to POST /v2/conversations/fast. To set or rotate the PAL’s default secret, Patch PAL using an add operation on /callback_secret. To disable signing while keeping its URL, set /callback_secret to null or remove that field:

[
  { "op": "add", "path": "/callback_secret", "value": null }
]

Changing the PAL’s default URL to a different destination clears its old secret. Include a replacement secret in the same patch to keep signing enabled at the new destination.

Verify the raw request body

Configure your receiver to require signatures once signing is enabled. Verify the signature before parsing or acting on the JSON. Re-serializing parsed JSON can change whitespace or Unicode encoding and invalidate the signature. Keep your shared secret in server-side configuration.

import hashlib
import hmac
import os
from flask import Flask, abort, request

app = Flask(__name__)
secret = os.environ["TAVUS_WEBHOOK_SECRET"].encode("utf-8")

@app.post("/webhooks/tavus")
def receive_callback():
    raw_body = request.get_data()
    expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
    supplied = request.headers.get("X-Tavus-Signature", "")
    if not hmac.compare_digest(expected.encode("ascii"), supplied.encode("utf-8")):
        abort(401)
    event = request.get_json()
    # Process the verified event here.
    return "", 200

import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";

const app = express();
const secret = process.env.TAVUS_WEBHOOK_SECRET;
if (!secret) throw new Error("TAVUS_WEBHOOK_SECRET is required");

// Register this route before any middleware that parses JSON bodies.
app.post("/webhooks/tavus", express.raw({ type: "application/json" }), (req, res) => {
  const supplied = req.get("X-Tavus-Signature") ?? "";
  if (!/^[0-9a-f]{64}$/.test(supplied)) return res.sendStatus(401);
  const expected = createHmac("sha256", secret).update(req.body).digest();
  if (!timingSafeEqual(expected, Buffer.from(supplied, "hex"))) {
    return res.sendStatus(401);
  }
  const event = JSON.parse(req.body.toString("utf8"));
  // Process the verified event here.
  return res.sendStatus(200);
});

Callbacks emitted in both legacy and PAL/face vocabulary carry separate signatures over their respective bodies. Verify each request independently. The signature authenticates the body, but does not provide replay protection or prove delivery order. Deduplicate events before applying non-idempotent side effects. No signing secret or internal signing context is included in the callback body.

Conversation Callbacks

Set a default callback_url on a PAL to receive conversation webhooks for conversations created with that PAL. You can also set callback_url on Create Conversation to choose a URL for an individual conversation. These callbacks report system events (such as the PAL joining and the room shutting down) and application events (such as final transcripts and recording availability).

PAL default and conversation override

The callback URL is resolved when you create the conversation:

A non-empty callback_url on Create Conversation takes priority.
If the conversation omits callback_url or passes an empty string, the PAL’s callback_url is used.
If neither has a URL, no conversation callbacks are sent.

The conversation override applies only to that conversation and does not change the PAL’s saved default. Callbacks go to the resolved URL, rather than being sent to both URLs. For example, create a PAL with a default callback URL:

{
  "pal_name": "Support assistant",
  "system_prompt": "Help customers with their support questions.",
  "default_face_id": "rc9cff32ceba",
  "callback_url": "https://yourwebsite.com/webhooks/pal"
}

Create a conversation with the returned pal_id and omit callback_url to use that default:

{
  "pal_id": "pcb7a34da5fe"
}

To send one conversation’s callbacks to a different endpoint, provide its own URL:

{
  "pal_id": "pcb7a34da5fe",
  "callback_url": "https://yourwebsite.com/webhooks/conversation"
}

This conversation sends callbacks to /webhooks/conversation. Future conversations that omit callback_url still use /webhooks/pal. To change the PAL’s default later, Patch PAL with an add operation at /callback_url (which also replaces an existing value). To clear the default, replace /callback_url with null.

Callback payload

All Conversation callbacks share the following basic structure. Differences will occur in the properties object.

{
    "properties": {
    "face_id": "<face_id>"
    },
    "conversation_id": "<conversation_id>",
    "webhook_url": "<webhook_url>",
    "event_type": "<event_type>",
    "message_type": "<system/application>",
    "timestamp": "<timestamp>"
}

Types

Our callbacks are split into two main categories:

System Callbacks

These callbacks are to provide insight into system-related events in a conversation. They are:

system.pal_joined: Fired when the PAL is ready for a conversation. Use this in new integrations.
system.replica_joined: Legacy duplicate of system.pal_joined with an identical payload. Still sent so existing integrations keep working; prefer system.pal_joined for new code.
system.shutdown: This is fired when the room shuts down, for any of the following reasons:
- max_call_duration reached
- participant_left_timeout reached
- participant_absent_timeout reached
- bot_could_not_join_meeting_it_was_probably_ended
- daily_room_has_been_deleted
- exception_encountered_during_conversation_startup
- end_conversation_endpoint_hit
- internal error occurred at step x

Examples:

{
  "properties": {
    "face_id": "<face_id>"
  },
  "conversation_id": "<conversation_id>",
  "webhook_url": "<webhook_url>",
  "event_type": "system.pal_joined",
  "message_type": "system",
  "timestamp": "2025-07-11T06:45:47.472000Z"
}

{
  "properties": {
    "face_id": "<face_id>"
  },
  "conversation_id": "<conversation_id>",
  "webhook_url": "<webhook_url>",
  "event_type": "system.replica_joined",
  "message_type": "system",
  "timestamp": "2025-07-11T06:45:47.472000Z"
}

{
  "properties": {
    "face_id": "<face_id>",
    "shutdown_reason": "participant_left_timeout"
  },
  "conversation_id": "<conversation_id>",
  "webhook_url": "<webhook_url>",
  "event_type": "system.shutdown",
  "message_type": "system",
  "timestamp": "2025-07-11T06:48:37.564961Z"
}

Application Callbacks

These callbacks are to inform developers about logical events that take place. They are:

application.transcription_ready: This is fired after ending a conversation, where the chat history is saved and returned. Each transcript entry includes role, content, timestamp (Unix epoch float, seconds, when the turn began - same field name as live interaction events), seconds_from_start, duration (seconds, float - same field name as the duration on conversation.stopped_speaking), and inference_id (on assistant turns). When the conversation knows who spoke, a user turn also has participant_name. It is the same name as on conversation.utterance. content never includes the name. The same payload is also available on the verbose GET conversation response under events (look for the event with event_type: "application.transcription_ready").
application.recording_ready: This is fired once your recording is durably written to your storage destination. Includes storage_provider (s3 / gcs / azure_blob) and a fully-qualified storage_uri so the same handler works across providers. See Recording Storage to set up GCS, Azure, or S3-in-any-region destinations.
application.recording_copy_failed: This is fired only on the worker-copy path (GCS, Azure, or S3 in regions Daily doesn’t support natively) when Tavus is unable to deliver the recording into your bucket after retries. Daily’s default storage retains the recording for ~30 days as a manual recovery window. Common causes: customer IAM trust policy mismatch, federated credential drift, bucket region typo. Use this as the canary for misconfiguration in your end.
application.perception_analysis: This is fired after ending a conversation, when the PAL has finished summarizing the visual artifacts that were detected throughout the call. This is a feature that is only available when the PAL has raven-1 specified in the Perception Layer.
application.post_call_action_executed: This is fired once for each post-call action Tavus runs after the conversation ends, recording the outcome (tool_name, status, and the request / response). The same payload is also available on the verbose GET conversation response under events.

Examples:

{
  "properties": {
    "face_id": "<face_id>",
    "transcript": [
      {
        "role": "user",
        "content": "Hi.",
        "timestamp": 1779475660.12,
        "seconds_from_start": 4.43,
        "duration": 0.42,
        "participant_name": "Alex Kim"
      },
      {
        "role": "assistant",
        "content": "Hello! How can I help?",
        "timestamp": 1779475661.04,
        "seconds_from_start": 5.35,
        "duration": 1.62,
        "inference_id": "inf_abc123"
      },
      {
        "role": "user",
        "content": "Quick question about my order.",
        "timestamp": 1779475665.21,
        "seconds_from_start": 9.52,
        "duration": 2.18,
        "participant_name": "Sam Rivera"
      },
      {
        "role": "assistant",
        "content": "Sure - what's the order number?",
        "timestamp": 1779475668.30,
        "seconds_from_start": 12.61,
        "duration": 2.05,
        "inference_id": "inf_def456"
      }
    ]
  },
  "conversation_id": "<conversation_id>",
  "webhook_url": "<webhook_url>",
  "event_type": "application.transcription_ready",
  "message_type": "application",
  "timestamp": "2025-07-11T06:48:37.566057Z"
}

{
  "properties": {
    "bucket_name": "<bucket_name>",
    "s3_key": "<object_key>",
    "duration": 14,
    "storage_provider": "s3",
    "storage_uri": "s3://<bucket_name>/<object_key>"
  },
  "conversation_id": "<conversation_id>",
  "webhook_url": "<webhook_url>",
  "event_type": "application.recording_ready",
  "message_type": "application",
  "timestamp": "2025-06-19T06:55:18.137386Z"
}

{
  "properties": {
    "recording_id": "<daily_recording_id>",
    "s3_key": "<intended_object_key>",
    "duration": 14,
    "storage_provider": "gcs",
    "error_code": "DESTINATION_AUTH_FAILED",
    "error_message": "GCS token exchange failed: invalid Workload Identity Provider"
  },
  "conversation_id": "<conversation_id>",
  "webhook_url": "<webhook_url>",
  "event_type": "application.recording_copy_failed",
  "message_type": "application",
  "timestamp": "2026-04-30T22:11:14Z"
}

{
  "properties": {
    "analysis": "Example summary: participant visible at a desk, neutral lighting, engaged tone. (Real payloads can be much longer.)"
  },
  "conversation_id": "<conversation_id>",
  "webhook_url": "<webhook_url>",
  "message_type": "application",
  "event_type": "application.perception_analysis",
  "timestamp": "2025-07-11T06:51:37.591677Z"
}

{
  "properties": {
    "tool_id": "<tool_id>",
    "tool_name": "post_call_summary",
    "status": "success",
    "request": {
      "url": "https://your-app.example.com/hooks/call-summary",
      "method": "POST",
      "body": "{\"channel\":\"C0SUPPORT\",\"text\":\"Caller asked about order status; resolved.\"}"
    },
    "response": { "http_status": 200, "body": "ok" }
  },
  "conversation_id": "<conversation_id>",
  "webhook_url": "<webhook_url>",
  "event_type": "application.post_call_action_executed",
  "message_type": "application",
  "timestamp": "2026-04-29T03:47:05Z"
}

Guardrail Callbacks

If a callback_url is provided on a guardrail, a callback is sent when that guardrail is triggered during a conversation.

{
  "conversation_id": "<conversation_id>",
  "properties": {
    "guardrail": "<guardrails_name>",
    "guardrail_uuid": "<guardrail_uuid>"
  }
}

Objective Callbacks

If a callback_url is provided on an objective, a callback is sent when that objective is completed during a conversation.

{
  "conversation_id": "<conversation_id>",
  "objective_name": "<objective_name>",
  "output_variables": {
    "<variable_name>": "<value>"
  }
}

Face Training Callbacks

If a callback_url is provided in the POST /faces call, you will receive a callback on face training completion or on face training error.

Dual delivery during the replica → face rename. While the API transitions from replica to face, each training event triggers two POSTs to the same callback_url: first the legacy payload with replica_id (for backward compatibility), then a second payload with face_id. Both POSTs share the same UUID value, the same status, and, on error, the same error_message - only the id field name differs.To handle this cleanly:

Distinguish the two payloads by which id field is present (replica_id vs. face_id).
De-duplicate on your side by treating replica_id and face_id as the same identifier for a given training event.
New integrations should key off face_id; the replica_id twin will be removed once the legacy field is retired.

Face Training Completed
Face Training Error

Legacy payload (replica_id)

{
    "replica_id": "rxxxxxxxxx",
    "status": "ready"
}

New payload (face_id)

{
    "face_id": "rxxxxxxxxx",
    "status": "ready"
}

On error, the error_message parameter will contain the error message. You can learn more about API Errors and Status Details here

Legacy payload (replica_id)

{
    "replica_id": "rxxxxxxxxx",
    "status": "error",
    "error_message": "There was an issue processing your training video. The video provided does not meet the minimum duration requirement for training"
}

New payload (face_id)

{
    "face_id": "rxxxxxxxxx",
    "status": "error",
    "error_message": "There was an issue processing your training video. The video provided does not meet the minimum duration requirement for training"
}

Video Generation Callbacks

If a callback_url is provided in the POST /videos call, you will receive callbacks on video generation completed and on video error.

Video Generation Completed
Video Generation Error

{
    "created_at": "2024-08-28 15:27:40.824457",
    "data": {
    "script": "Hello this is a test to give examples of callbacks"
    },
    "download_url": "https://stream.mux.com/H5H029h02tY7XDpNj9JFDbLleTyUpsJr5npddO8gRsKqY/high.mp4?download=1e30440cf9",
    "generation_progress": "100/100",
    "hosted_url": "https://videos.tavus.io/video/1e30440cf9",
    "face_id": "rc9cff32ceba",
    "status": "ready",
    "status_details": "Your request has processed successfully!",
    "stream_url": "https://stream.mux.com/H5H029h02tY7XDpNj9JFDbLleTyUpsJr5npddO8gRsKqY.m3u8",
    "updated_at": "2024-08-28 15:29:19.802670",
    "video_id": "1e30440cf9",
    "video_name": "face_id: rc9cff32ceba - August 28, 2024 - video: 1e30440cf9"
}

On error, the status_details parameter will contain the error message. You can learn more about API Errors and Status Details here

{
    "created_at": "2024-08-28 15:32:53.058894",
    "data": {
    "script": "This is a test script to show how videos error"
    },
    "download_url": null,
    "error_details": null,
    "generation_progress": "0/100",
    "hosted_url": "https://videos.tavus.io/video/c9b85a6d36",
    "face_id": "rc9cff32ceba",
    "status": "error",
    "status_details": "An error occurred while generating this request. Please check your inputs or try your request again.",
    "stream_url": null,
    "updated_at": "2024-08-28 15:35:03.762392",
    "video_id": "c9b85a6d36",
    "video_name": "face_id: rc9cff32ceba - August 28, 2024 - video: c9b85a6d36"
}

Sample Webhook Setup

Create a sample webhook endpoint using Python Flask, and expose it publicly with ngrok.

Prerequisites

Python
Ngrok

Step 1: Install Python Dependencies

Install the Python dependencies needed to create the server.

pip install flask requests

Step 2: Make a Webhook Server

Set up a webhook server and save it as server.py.

import requests
from flask import Flask, request, jsonify

app = Flask(__name__)

# Store transcripts (in production, use a proper database)
transcripts = {}

@app.route('/webhook', methods=['POST'])
def handle_tavus_callback():
    data = request.json
    event_type = data.get('event_type')
    conversation_id = data.get('conversation_id')
    
    print(f"Received callback: {event_type} for conversation {conversation_id}")
    
    if event_type in ('system.pal_joined', 'system.replica_joined'):
        print("✅ PAL has joined the conversation")
        
    elif event_type == 'system.shutdown':
        shutdown_reason = data['properties'].get('shutdown_reason')
        print(f"🔚 Conversation ended: {shutdown_reason}")
    
    elif event_type == 'application.recording_ready':
        s3_key = data['properties'].get('s3_key')
        print(f"s3_key : {s3_key}")

    elif event_type == 'application.perception_analysis':
        analysis = data['properties'].get('analysis')
        print(f"analysis : {analysis}")
        
    elif event_type == 'application.transcription_ready':
        print("📝 Transcript is ready!")
        transcript = data['properties']['transcript']
        transcripts[conversation_id] = transcript
        
        # Process the transcript
        analyze_conversation(conversation_id, transcript)
        
    return jsonify({"status": "success"}), 200

def analyze_conversation(conversation_id, transcript):
    """Analyze the conversation transcript"""
    user_turns = len([msg for msg in transcript if msg['role'] == 'user'])
    assistant_turns = len([msg for msg in transcript if msg['role'] == 'assistant'])
    speakers = {msg['participant_name'] for msg in transcript if msg.get('participant_name')}
    
    print(f"Conversation {conversation_id} analysis:")
    print(f"- User turns: {user_turns}")
    print(f"- Assistant turns: {assistant_turns}")
    print(f"- Total messages: {len(transcript)}")
    print(f"- Speakers: {sorted(speakers)}")

    print("Conversation : ")

    for msg in transcript:
        print(f"{msg['role']} : {msg['content']}")

if __name__ == '__main__':
    app.run(port=5000, debug=True)

The server will receive and process webhook callbacks from Tavus, handle different event types, store transcripts in memory, and analyze conversation data for each session.

Step 3: Run the Server

Run the app using the following command in the terminal:

python server.py

The server should run on port 5000.

Step 4: Forward the Port Using Ngrok

With ngrok installed and on your PATH, forward the port from a terminal (on Windows you can run ngrok.exe from the install folder instead).

ngrok http 5000

The command will generate a forwarding link (e.g., https://1234567890.ngrok-free.app), which can be used as the callback URL.

Step 5: Use the Callback URL

Include the callback URL in your request to Tavus by appending /webhook to the forwarding link and setting it in the callback_url field.

Create conversation with callback_url

curl --request POST \
  --url https://tavusapi.com/v2/conversations \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "callback_url": "https://1234567890.ngrok-free.app/webhook",
  "face_id": "<face_id>",
  "pal_id": "<pal_id>"
}'

Replace <api-key> with your actual API key. You can generate one in the PAL Maker.
Replace <face_id> with the Face ID you want to use.
Replace <pal_id> with the PAL ID you want to use.

Getting Started

Guides

Build

Deploy

Debug

Teams & SSO

Resources