Post-call webhooks

Overview

Post-call Webhooks allow you to receive detailed information about a call after analysis is complete. When enabled, ElevenLabs will send a POST request to your specified endpoint with comprehensive call data.

ElevenLabs supports three types of post-call webhooks:

• Transcription webhooks (post_call_transcription): Contains full conversation data including transcripts, analysis results, and metadata
• Audio webhooks (post_call_audio): Contains minimal data with base64-encoded audio of the full conversation
• Call initiation failure webhooks (call_initiation_failure): Contains information about failed call initiation attempts including failure reasons and metadata

Migration Notice: Enhanced Webhook Format

What’s Changing

Post-call transcription webhooks will be updated to match the same format as the GET Conversation response. The webhook data object will include three additional boolean fields:

• has_audio: Boolean indicating whether the conversation has any audio available
• has_user_audio: Boolean indicating whether user audio is available for the conversation
• has_response_audio: Boolean indicating whether agent response audio is available for the conversation

Migration Requirements

To ensure your webhook handlers continue working after the migration:

1. Update your webhook parsing logic to handle these three new boolean fields
2. Test your webhook endpoints with the new field structure before August 15th, 2025
3. Ensure your JSON parsing can gracefully handle additional fields without breaking

Benefits After Migration

Once the migration is complete:

• Unified data model: Webhook responses will match the GET Conversation API format exactly
• SDK compatibility: Webhook handlers can be provided in the SDK and automatically stay up-to-date with the GET response model

Enabling post-call webhooks

Post-call webhooks can be enabled for all agents in your workspace through the ElevenAgents settings page.

Authentication

It is important for the listener to validate all incoming webhooks. Webhooks currently support authentication via HMAC signatures. Set up HMAC authentication by:

• Securely storing the shared secret generated upon creation of the webhook
• Verifying the ElevenLabs-Signature header in your endpoint using the SDK

The JavaScript SDK exposes constructEvent; the Python SDK exposes construct_event with rawBody, sig_header, and secret (these are not named payload / signature in Python). Both verify the signature, validate the timestamp, and parse the JSON payload.

1
from dotenv import load_dotenv
2
from fastapi import FastAPI, Request
3
from fastapi.responses import JSONResponse
4
from elevenlabs.client import ElevenLabs
5
import os
6
7
load_dotenv()
8
9
app = FastAPI()
10
elevenlabs = ElevenLabs(
11
    api_key=os.getenv("ELEVENLABS_API_KEY"),
12
)
13
14
WEBHOOK_SECRET = os.getenv("WEBHOOK_SECRET")
15
16
@app.post("/webhook")
17
async def receive_message(request: Request):
18
    payload = await request.body()
19
    signature = request.headers.get("elevenlabs-signature")
20
21
    try:
22
        event = elevenlabs.webhooks.construct_event(
23
            rawBody=payload.decode("utf-8"),
24
            sig_header=signature,
25
            secret=WEBHOOK_SECRET,
26
        )
27
    except Exception as e:
28
        return JSONResponse(content={"error": "Invalid signature"}, status_code=401)
29
30
    # construct_event returns a dict (parsed JSON), not an object with attributes
31
    if event.get("type") == "post_call_transcription":
32
        print(f"Received transcription: {event.get('data')}")
33
34
    return {"status": "received"}

IP whitelisting

For additional security, you can whitelist the following static egress IPs from which ElevenLabs requests originate:

If you are using a data residency region then the following IPs will be used:

If your infrastructure requires strict IP-based access controls, adding these IPs to your firewall allowlist will ensure you only receive requests from ElevenLabs’ systems.

Webhook response structure

ElevenLabs sends three distinct types of post-call webhooks, each with different data structures:

Transcription webhooks (post_call_transcription)

Contains comprehensive conversation data including full transcripts, analysis results, and metadata.

Top-level fields

Data object structure

The data object contains:

Audio webhooks (post_call_audio)

Contains minimal data with the full conversation audio as base64-encoded MP3.

Top-level fields

Data object structure

The data object contains only:

Call initiation failure webhooks (call_initiation_failure)

Contains information about telephony call initiation attempts, including failure reasons and telephony-provider metadata.

Top-level fields

Data object structure

The data object contains:

Metadata object structure

The metadata object structure varies depending on whether the outbound call was made via Twilio or via SIP trunking. The object includes a type field that distinguishes between the two, and a body field containing provider-specific details.

SIP metadata (type: "sip"):

The body object for SIP metadata contains:

Twilio metadata (type: "twilio"):

Example webhook payloads

Transcription webhook example

1
{
2
  "type": "post_call_transcription",
3
  "event_timestamp": 1739537297,
4
  "data": {
5
    "agent_id": "xyz",
6
    "conversation_id": "abc",
7
    "status": "done",
8
    "user_id": "user123",
9
    "transcript": [
10
      {
11
        "role": "agent",
12
        "message": "Hey there angelo. How are you?",
13
        "tool_calls": null,
14
        "tool_results": null,
15
        "feedback": null,
16
        "time_in_call_secs": 0,
17
        "conversation_turn_metrics": null
18
      },
19
      {
20
        "role": "user",
21
        "message": "Hey, can you tell me, like, a fun fact about 11 Labs?",
22
        "tool_calls": null,
23
        "tool_results": null,
24
        "feedback": null,
25
        "time_in_call_secs": 2,
26
        "conversation_turn_metrics": null
27
      },
28
      {
29
        "role": "agent",
30
        "message": "I do not have access to fun facts about Eleven Labs. However, I can share some general information about the company. Eleven Labs is an AI voice technology platform that specializes in voice cloning and text-to-speech...",
31
        "tool_calls": null,
32
        "tool_results": null,
33
        "feedback": null,
34
        "time_in_call_secs": 9,
35
        "conversation_turn_metrics": {
36
          "convai_llm_service_ttfb": {
37
            "elapsed_time": 0.3704247010173276
38
          },
39
          "convai_llm_service_ttf_sentence": {
40
            "elapsed_time": 0.5551181449554861
41
          }
42
        }
43
      }
44
    ],
45
    "metadata": {
46
      "start_time_unix_secs": 1739537297,
47
      "call_duration_secs": 22,
48
      "cost": 296,
49
      "deletion_settings": {
50
        "deletion_time_unix_secs": 1802609320,
51
        "deleted_logs_at_time_unix_secs": null,
52
        "deleted_audio_at_time_unix_secs": null,
53
        "deleted_transcript_at_time_unix_secs": null,
54
        "delete_transcript_and_pii": true,
55
        "delete_audio": true
56
      },
57
      "feedback": {
58
        "overall_score": null,
59
        "likes": 0,
60
        "dislikes": 0
61
      },
62
      "authorization_method": "authorization_header",
63
      "charging": {
64
        "dev_discount": true
65
      },
66
      "termination_reason": ""
67
    },
68
    "analysis": {
69
      "evaluation_criteria_results": {},
70
      "data_collection_results": {},
71
      "call_successful": "success",
72
      "transcript_summary": "The conversation begins with the agent asking how Angelo is, but Angelo redirects the conversation by requesting a fun fact about 11 Labs. The agent acknowledges they don't have specific fun facts about Eleven Labs but offers to provide general information about the company. They briefly describe Eleven Labs as an AI voice technology platform specializing in voice cloning and text-to-speech technology. The conversation is brief and informational, with the agent adapting to the user's request despite not having the exact information asked for."
73
    },
74
    "conversation_initiation_client_data": {
75
      "conversation_config_override": {
76
        "agent": {
77
          "prompt": null,
78
          "first_message": null,
79
          "language": "en"
80
        },
81
        "tts": {
82
          "voice_id": null
83
        }
84
      },
85
      "custom_llm_extra_body": {},
86
      "dynamic_variables": {
87
        "user_name": "angelo"
88
      },
89
      "branch_id": null,
90
      "environment": null
91
    }
92
  }
93
}

Audio webhook example

1
{
2
  "type": "post_call_audio",
3
  "event_timestamp": 1739537319,
4
  "data": {
5
    "agent_id": "xyz",
6
    "conversation_id": "abc",
7
    "full_audio": "SUQzBAAAAAAA...base64_encoded_mp3_data...AAAAAAAAAA=="
8
  }
9
}

Call initiation failure webhook examples

Twilio metadata example

1
{
2
  "type": "call_initiation_failure",
3
  "event_timestamp": 1759931652,
4
  "data": {
5
    "agent_id": "xyz",
6
    "conversation_id": "abc",
7
    "failure_reason": "busy",
8
    "metadata": {
9
      "type": "twilio",
10
      "body": {
11
        "Called": "+441111111111",
12
        "ToState": "",
13
        "CallerCountry": "US",
14
        "Direction": "outbound-api",
15
        "Timestamp": "Wed, 08 Oct 2025 13:54:12 +0000",
16
        "CallbackSource": "call-progress-events",
17
        "SipResponseCode": "487",
18
        "CallerState": "WA",
19
        "ToZip": "",
20
        "SequenceNumber": "2",
21
        "CallSid": "CA8367245817625617832576245724",
22
        "To": "+441111111111",
23
        "CallerZip": "98631",
24
        "ToCountry": "GB",
25
        "CalledZip": "",
26
        "ApiVersion": "2010-04-01",
27
        "CalledCity": "",
28
        "CallStatus": "busy",
29
        "Duration": "0",
30
        "From": "+11111111111",
31
        "CallDuration": "0",
32
        "AccountSid": "AC37682153267845716245762454a",
33
        "CalledCountry": "GB",
34
        "CallerCity": "RAYMOND",
35
        "ToCity": "",
36
        "FromCountry": "US",
37
        "Caller": "+11111111111",
38
        "FromCity": "RAYMOND",
39
        "CalledState": "",
40
        "FromZip": "12345",
41
        "FromState": "WA"
42
      }
43
    }
44
  }
45
}

SIP metadata example

1
{
2
  "type": "call_initiation_failure",
3
  "event_timestamp": 1759931652,
4
  "data": {
5
    "agent_id": "xyz",
6
    "conversation_id": "abc",
7
    "failure_reason": "busy",
8
    "metadata": {
9
      "type": "sip",
10
      "body": {
11
        "from_number": "+441111111111",
12
        "to_number": "+11111111111",
13
        "sip_status_code": 486,
14
        "error_reason": "INVITE failed: sip status: 486: Busy here (SIP 486)",
15
        "call_sid": "d8e7f6a5-b4c3-4d5e-8f9a-0b1c2d3e4f5a",
16
        "sip_status": "Busy here",
17
        "twirp_code": "unavailable"
18
      }
19
    }
20
  }
21
}

Audio webhook delivery

Audio webhooks are delivered separately from transcription webhooks and contain only the essential fields needed to identify the conversation along with the base64-encoded audio data.

Streaming delivery

Audio webhooks are delivered as streaming HTTP requests with the transfer-encoding: chunked header to handle large audio files efficiently.

Processing audio webhooks

Since audio webhooks are delivered via chunked transfer encoding, you’ll need to handle streaming data properly:

1
import base64
2
import json
3
from aiohttp import web
4
5
async def handle_webhook(request):
6
7
    # Check if this is a chunked/streaming request
8
    if request.headers.get("transfer-encoding", "").lower() == "chunked":
9
        # Read streaming data in chunks
10
        chunked_body = bytearray()
11
        while True:
12
            chunk = await request.content.read(8192)  # 8KB chunks
13
            if not chunk:
14
                break
15
            chunked_body.extend(chunk)
16
17
        # Parse the complete payload
18
        request_body = json.loads(chunked_body.decode("utf-8"))
19
    else:
20
        # Handle regular requests
21
        body_bytes = await request.read()
22
        request_body = json.loads(body_bytes.decode('utf-8'))
23
24
    # Process different webhook types
25
    if request_body["type"] == "post_call_transcription":
26
        # Handle transcription webhook with full conversation data
27
        handle_transcription_webhook(request_body["data"])
28
    elif request_body["type"] == "post_call_audio":
29
        # Handle audio webhook with minimal data
30
        handle_audio_webhook(request_body["data"])
31
    elif request_body["type"] == "call_initiation_failure":
32
        # Handle call initiation failure webhook
33
        handle_call_initiation_failure_webhook(request_body["data"])
34
35
    return web.json_response({"status": "ok"})
36
37
def handle_audio_webhook(data):
38
    # Decode base64 audio data
39
    audio_bytes = base64.b64decode(data["full_audio"])
40
41
    # Save or process the audio file
42
    conversation_id = data["conversation_id"]
43
    with open(f"conversation_{conversation_id}.mp3", "wb") as f:
44
        f.write(audio_bytes)
45
46
def handle_call_initiation_failure_webhook(data):
47
    # Handle call initiation failure events
48
    agent_id = data["agent_id"]
49
    conversation_id = data["conversation_id"]
50
    failure_reason = data.get("failure_reason")
51
    metadata = data.get("metadata", {})
52
53
    # Log the failure for monitoring
54
    print(f"Call failed for agent {agent_id}, conversation {conversation_id}")
55
    print(f"Failure reason: {failure_reason}")
56
57
    # Access provider-specific metadata
58
    provider_type = metadata.get("type")
59
    body = metadata.get("body", {})
60
    if provider_type == "sip":
61
        print(f"SIP status code: {body.get('sip_status_code')}")
62
        print(f"Error reason: {body.get('error_reason')}")
63
    elif provider_type == "twilio":
64
        print(f"Twilio CallSid: {body.get('CallSid')}")
65
        print(f"Call status: {body.get('CallStatus')}")
66
67
    # Update your system with the failure information
68
    # e.g., mark lead as "call_failed" in CRM

Use cases

Automated call follow-ups

Post-call webhooks enable you to build automated workflows that trigger immediately after a call ends. Here are some practical applications:

CRM integration

Update your customer relationship management system with conversation data as soon as a call completes:

1
// Example webhook handler
2
app.post("/webhook/elevenlabs", async (req, res) => {
3
  // HMAC validation code
4
5
  const { data } = req.body;
6
7
  // Extract key information
8
  const userId = data.metadata.user_id;
9
  const transcriptSummary = data.analysis.transcript_summary;
10
  const callSuccessful = data.analysis.call_successful;
11
12
  // Update CRM record
13
  await updateCustomerRecord(userId, {
14
    lastInteraction: new Date(),
15
    conversationSummary: transcriptSummary,
16
    callOutcome: callSuccessful,
17
    fullTranscript: data.transcript,
18
  });
19
20
  res.status(200).send("Webhook received");
21
});

Stateful conversations

Maintain conversation context across multiple interactions by storing and retrieving state:

1. When a call starts, pass in your user id as a dynamic variable.
2. When a call ends, set up your webhook endpoint to store conversation data in your database, based on the extracted user id from the dynamic_variables.
3. When the user calls again, you can retrieve this context and pass it to the new conversation into a {{previous_topics}} dynamic variable.
4. This creates a seamless experience where the agent “remembers” previous interactions

1
// Store conversation state when call ends
2
app.post("/webhook/elevenlabs", async (req, res) => {
3
  // HMAC validation code
4
5
  const { data } = req.body;
6
  const userId = data.metadata.user_id;
7
8
  // Store conversation state
9
  await db.userStates.upsert({
10
    userId,
11
    lastConversationId: data.conversation_id,
12
    lastInteractionTimestamp: data.metadata.start_time_unix_secs,
13
    conversationHistory: data.transcript,
14
    previousTopics: extractTopics(data.analysis.transcript_summary),
15
  });
16
17
  res.status(200).send("Webhook received");
18
});
19
20
// When initiating a new call, retrieve and use the state
21
async function initiateCall(userId) {
22
  // Get user's conversation state
23
  const userState = await db.userStates.findOne({ userId });
24
25
  // Start new conversation with context from previous calls
26
  return await elevenlabs.startConversation({
27
    agent_id: "xyz",
28
    conversation_id: generateNewId(),
29
    dynamic_variables: {
30
      user_name: userState.name,
31
      previous_conversation_id: userState.lastConversationId,
32
      previous_topics: userState.previousTopics.join(", "),
33
    },
34
  });
35
}