नेविगेशन पर जाएँ

वेबहुक्स

वेबहुक इवेंट पाकर बाहरी इंटीग्रेशन सक्षम करें।

खास जानकारी

ElevenLabs में कुछ इवेंट्स को वेबहुक ट्रिगर करने के लिए कॉन्फ़िगर किया जा सकता है। इससे बाहरी ऐप्लिकेशन और सिस्टम इन इवेंट्स के होने पर उन्हें पा और प्रोसेस कर सकते हैं। फ़िलहाल ये इवेंट टाइप समर्थित हैं:

इवेंट टाइपजानकारी
post_call_transcriptionAgents Platform की एक कॉल खत्म हो गई है और उसका विश्लेषण पूरा हो गया है
voice_removal_noticeकिसी शेयर की गई वॉइस को हटाने का समय तय किया गया है
voice_removal_notice_withdrawnकिसी शेयर की गई वॉइस को अब हटाने का समय तय नहीं है
voice_removedकिसी शेयर की गई वॉइस को हटा दिया गया है और अब उसका इस्तेमाल नहीं किया जा सकता
flows_generationइमेज और वीडियो जनरेशन पूरा हो गया है या विफल हो गया है
flows_template_runएक टेम्पलेट रन पूरा हो गया है या विफल हो गया है

कॉन्फ़िगरेशन

वेबहुक्स को सामान्य सेटिंग्स पेज से बनाया, निष्क्रिय और हटाया जा सकता है। वर्कस्पेसेस में मौजूद यूज़र्स के लिए, सिर्फ़ वर्कस्पेस एडमिन ही वर्कस्पेस के वेबहुक्स कॉन्फ़िगर कर सकते हैं।

HMAC वेबहुक कॉन्फ़िगरेशन

बनाने के बाद, वेबहुक को Agents Platform जैसी प्रोडक्ट सेटिंग्स में इवेंट्स सुनने के लिए चुना जा सकता है।

flows_generation और flows_template_run इवेंट्स, दोनों एक ही सब्सक्रिप्शन से सक्षम होते हैं: सुनने के लिए इवेंट्स चुनें में इमेज और वीडियो API जनरेशन या टेम्पलेट रन पूरा हुआ को चुनें, या वर्कस्पेस वेबहुक अपडेट करें को flows इवेंट पास करें। जनरेशन या रन अपना इवेंट सिर्फ़ तभी भेजता है, जब उसके क्रिएट रिक्वेस्ट में webhook फ़ील्ड शामिल हो।

वेबहुक्स को कभी भी सामान्य सेटिंग्स पेज से निष्क्रिय किया जा सकता है। अगर लगातार 10 या उससे ज़्यादा डिलीवरी विफल हों और आखिरी सफल डिलीवरी 7 दिन से ज़्यादा पहले हुई हो या कभी सफल डिलीवरी न हुई हो, तो बार-बार विफल होने वाले वेबहुक्स अपने-आप निष्क्रिय हो जाते हैं। अपने-आप निष्क्रिय हुए वेबहुक्स को सेटिंग्स पेज से फिर से सक्षम करना होगा। जिन वेबहुक्स का इस्तेमाल किसी प्रोडक्ट में नहीं हो रहा है, उन्हें हटाया जा सकता है।

फिर से कोशिश

रिक्वेस्ट विफल होने पर डिलीवरी की अपने-आप फिर से कोशिश करने के लिए, हर वेबहुक के लिए रिट्राई सक्षम किए जा सकते हैं। डिफ़ॉल्ट रूप से रिट्राई निष्क्रिय होते हैं। API से या वेबहुक सेटिंग्स में वेबहुक बनाते या अपडेट करते समय रिट्राई सक्षम करें।

रिट्राई ElevenAgents के पोस्ट-कॉल वेबहुक्स के लिए समर्थित हैं, जिनमें ट्रांसक्रिप्शन (post_call_transcription), ऑडियो (post_call_audio), और कॉल शुरू न होने के (call_initiation_failure) इवेंट्स शामिल हैं।

रिट्राई शेड्यूल

जब कोई डिलीवरी प्रयास रिट्राई किए जा सकने वाले एरर के साथ विफल होता है, तो सिस्टम प्रयासों के बीच बढ़ते अंतराल के साथ 5 बार तक फिर से कोशिश करता है:

प्रयासअंतराल
1तुरंत
230 सेकंड
32 मिनट
48 मिनट
530 मिनट

लोड को वितरित करने और थंडरिंग हर्ड समस्याओं से बचने के लिए, हर रिट्राई में थोड़ा रैंडम जिटर (अंतराल का 10% तक) जोड़ा जाता है।

रिट्राई किए जा सकने वाले एरर

हर विफलता पर रिट्राई ट्रिगर नहीं होता। सिर्फ़ इन विफलताओं को रिट्राई योग्य माना जाता है:

  • 5xx स्टेटस कोड (सर्वर एरर, जैसे 500, 502, 503, 504)।
  • 429 (बहुत ज़्यादा रिक्वेस्ट)।
  • 408 (रिक्वेस्ट टाइम आउट)।
  • कनेक्शन एरर और रिक्वेस्ट टाइम आउट।

4xx रेंज (जैसे 400, 401, 403, 404) के रिक्वेस्ट एरर पर फिर से कोशिश नहीं की जाती, क्योंकि वे आमतौर पर ऐसी कॉन्फ़िगरेशन समस्या बताते हैं जिसे मैन्युअल रूप से ठीक करना होता है।

हर वेबहुक के लिए क्यू सीमाएं

हर वेबहुक में अधिकतम 100 पेंडिंग रिट्राई जॉब हो सकती हैं। अगर किसी वेबहुक में 100 से ज़्यादा रिट्राई क्यू में जमा हो जाती हैं, तो मौजूदा रिट्राई प्रोसेस होने तक अतिरिक्त जॉब्स हटा दी जाती हैं। इससे कोई एक गलत कॉन्फ़िगर किया गया वेबहुक ज़रूरत से ज़्यादा रिसोर्स इस्तेमाल नहीं कर पाता।

ऑडियो वेबहुक्स की दो अतिरिक्त सीमाएं हैं। 50 MiB से बड़ा ऑडियो पेलोड एक बार डिलीवर किया जाता है और उसकी फिर से कोशिश नहीं होती, और एक वेबहुक के लिए क्यू में मौजूद ऑडियो रिट्राई कुल मिलाकर 400 MiB से ज़्यादा नहीं हो सकतीं।

अपने-आप निष्क्रिय होने का व्यवहार

सिस्टम हर वेबहुक के लिए लगातार डिलीवरी विफलताओं को ट्रैक करता है। नीचे दी गई दोनों शर्तें पूरी होने पर वेबहुक अपने-आप निष्क्रिय हो जाता है:

  • लगातार 10 या उससे ज़्यादा डिलीवरी विफलताएं हुई हैं।
  • वेबहुक की डिलीवरी कभी सफल नहीं हुई है, या आखिरी सफल डिलीवरी 7 दिन से ज़्यादा पहले हुई थी।

जब कोई वेबहुक अपने-आप निष्क्रिय होता है, तो वर्कस्पेस एडमिन को ईमेल सूचना मिलती है। डिलीवरी फिर से शुरू होने से पहले, वेबहुक को सेटिंग्स पेज से मैन्युअल रूप से फिर से सक्षम करना होगा।

इंटीग्रेशन

वेबहुक्स के साथ इंटीग्रेट करने के लिए, POST रिक्वेस्ट के रूप में वेबहुक इवेंट डेटा पाने वाला एंडपॉइंट हैंडलर बनाएं। सिग्नेचर की पुष्टि करने के बाद, सफलतापूर्वक मिलने की पुष्टि के लिए हैंडलर को तुरंत HTTP 200 लौटाना चाहिए। सफल रिस्पॉन्स बार-बार न लौटाने पर वेबहुक अपने-आप निष्क्रिय हो सकता है।

रिट्राई पेलोड मूल डिलीवरी प्रयास के समान होता है। वेबहुक उपभोक्ता सिर्फ़ पेलोड से शुरुआती डिलीवरी और रिट्राई में अंतर नहीं कर सकते, इसलिए अपने हैंडलर को idempotent बनाएं — एक ही इवेंट को कई बार प्रोसेस करने पर एक ही नतीजा मिलना चाहिए। ज़रूरत होने पर इवेंट्स को डुप्लिकेट होने से रोकने के लिए event_timestamp और इवेंट-विशिष्ट आइडेंटिफ़ायर्स (जैसे conversation_id) का इस्तेमाल करें।

टॉप-लेवल फ़ील्ड्स

फ़ील्डटाइपजानकारी
typestringइवेंट का टाइप
dataobjectइवेंट का डेटा
event_timestampnumberयह इवेंट Unix टाइम UTC में कब हुआ

वेबहुक पेलोड का उदाहरण

{
"type": "post_call_transcription",
"event_timestamp": 1739537297,
"data": {
"agent_id": "xyz",
"conversation_id": "abc",
"status": "done",
"transcript": [
{
"role": "agent",
"message": "Hey there angelo. How are you?",
"tool_calls": null,
"tool_results": null,
"feedback": null,
"time_in_call_secs": 0,
"conversation_turn_metrics": null
},
{
"role": "user",
"message": "Hey, can you tell me, like, a fun fact about 11 Labs?",
"tool_calls": null,
"tool_results": null,
"feedback": null,
"time_in_call_secs": 2,
"conversation_turn_metrics": null
},
{
"role": "agent",
"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...",
"tool_calls": null,
"tool_results": null,
"feedback": null,
"time_in_call_secs": 9,
"conversation_turn_metrics": {
"convai_llm_service_ttfb": {
"elapsed_time": 0.3704247010173276
},
"convai_llm_service_ttf_sentence": {
"elapsed_time": 0.5551181449554861
}
}
}
],
"metadata": {
"start_time_unix_secs": 1739537297,
"call_duration_secs": 22,
"cost": 296,
"deletion_settings": {
"deletion_time_unix_secs": 1802609320,
"deleted_logs_at_time_unix_secs": null,
"deleted_audio_at_time_unix_secs": null,
"deleted_transcript_at_time_unix_secs": null,
"delete_transcript_and_pii": true,
"delete_audio": true
},
"feedback": {
"overall_score": null,
"likes": 0,
"dislikes": 0
},
"authorization_method": "authorization_header",
"charging": {
"dev_discount": true
},
"termination_reason": ""
},
"analysis": {
"evaluation_criteria_results": {},
"data_collection_results": {},
"call_successful": "success",
"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."
},
"conversation_initiation_client_data": {
"conversation_config_override": {
"agent": {
"prompt": null,
"first_message": null,
"language": "en"
},
"tts": {
"voice_id": null
}
},
"custom_llm_extra_body": {},
"dynamic_variables": {
"user_name": "angelo"
}
}
}
}

वॉइस हटाने के वेबहुक्स

वर्कस्पेस को वॉइस लाइब्रेरी से जोड़ी गई किसी शेयर की गई वॉइस के लिए ये इवेंट्स मिलते हैं, जब वॉइस का मालिक या ElevenLabs उसे वॉइस लाइब्रेरी से हटाता है।

हटाने की सूचना (voice_removal_notice)

वॉइस के लिए एक सूचना अवधि होती है। वह future_removal_timestamp तक इस्तेमाल की जा सकती है।

सूचना अवधि खत्म होने पर कोई और इवेंट नहीं भेजा जाता।

डेटा ऑब्जेक्ट का स्ट्रक्चर

फ़ील्डटाइपजानकारी
voice_idstringउस वॉइस का ID जिसे हटाने का समय तय है
future_removal_timestampnumberवॉइस का इस्तेमाल कब बंद होगा, Unix टाइम UTC में
suggested_voicesarrayअधिकतम 3 मिलती-जुलती वॉइस। सुझाई गई वॉइस देखें
{
"type": "voice_removal_notice",
"event_timestamp": 1739537297,
"data": {
"voice_id": "21m00Tcm4TlvDq8ikWAM",
"future_removal_timestamp": 1742129297,
"suggested_voices": [
["https://elevenlabs.io/app/voice-lab/share/a1b2c3d4e5f6/EXAVITQu4vr4xnSDxMaL", "Sarah"]
]
}
}

हटाने की सूचना वापस ली गई (voice_removal_notice_withdrawn)

वॉइस को अब हटाने का समय तय नहीं है और वह इस्तेमाल की जा सकती है।

डेटा ऑब्जेक्ट का स्ट्रक्चर

फ़ील्डटाइपजानकारी
voice_idstringउस वॉइस का ID जिसे अब नहीं हटाया जा रहा है
{
"type": "voice_removal_notice_withdrawn",
"event_timestamp": 1739537297,
"data": {
"voice_id": "21m00Tcm4TlvDq8ikWAM"
}
}

वॉइस हटाई गई (voice_removed)

वॉइस को बिना सूचना अवधि के हटा दिया गया था और अब उसका इस्तेमाल नहीं किया जा सकता।

डेटा ऑब्जेक्ट का स्ट्रक्चर

फ़ील्डटाइपजानकारी
voice_idstringहटाई गई वॉइस का ID
suggested_voicesarrayअधिकतम 3 मिलती-जुलती वॉइस। सुझाई गई वॉइस देखें
{
"type": "voice_removed",
"event_timestamp": 1739537297,
"data": {
"voice_id": "21m00Tcm4TlvDq8ikWAM",
"suggested_voices": [
["https://elevenlabs.io/app/voice-lab/share/a1b2c3d4e5f6/EXAVITQu4vr4xnSDxMaL", "Sarah"]
]
}
}

सुझाई गई वॉइस

suggested_voices का हर आइटम दो आइटम वाली ऐरे है: वॉइस का वॉइस लाइब्रेरी शेयर URL, फिर वॉइस का नाम। सूची खाली हो सकती है।

ऑथेंटिकेशन

लिस्नर के लिए सभी इनकमिंग वेबहुक को वैलिडेट करना ज़रूरी है। वेबहुक फ़िलहाल HMAC सिग्नेचर के ज़रिए ऑथेंटिकेशन सपोर्ट करते हैं। HMAC ऑथेंटिकेशन सेट अप करने के लिए:

  • वेबहुक बनाते समय जनरेट हुए शेयर किए गए सीक्रेट को सुरक्षित रूप से स्टोर करें
  • SDK का इस्तेमाल करके अपने एंडपॉइंट में ElevenLabs-Signature हेडर को वेरिफ़ाई करें

JavaScript SDK में constructEvent और Python SDK में rawBody, sig_header, और secret के साथ construct_event उपलब्ध है (Python में इनके नाम payload / signature नहीं हैं)। दोनों सिग्नेचर वेरिफ़ाई करते हैं, टाइमस्टैम्प वैलिडेट करते हैं और JSON पेलोड पार्स करते हैं।

FastAPI का इस्तेमाल करने वाले वेबहुक हैंडलर का उदाहरण:

from dotenv import load_dotenv
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse
from elevenlabs.client import ElevenLabs
from elevenlabs.errors import BadRequestError
import os
load_dotenv()
app = FastAPI()
elevenlabs = ElevenLabs(
api_key=os.getenv("ELEVENLABS_API_KEY"),
)
WEBHOOK_SECRET = os.getenv("WEBHOOK_SECRET")
@app.post("/webhook")
async def receive_message(request: Request):
payload = await request.body()
signature = request.headers.get("elevenlabs-signature")
try:
event = elevenlabs.webhooks.construct_event(
rawBody=payload.decode("utf-8"),
sig_header=signature,
secret=WEBHOOK_SECRET,
)
except BadRequestError as e:
return JSONResponse(content={"error": "Invalid signature"}, status_code=401)
# construct_event returns a dict (parsed JSON), not an object with attributes
if event.get("type") == "post_call_transcription":
print(f"Received transcription: {event.get('data')}")
return {"status": "received"}