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

बनाने के बाद, वेबहुक को Agents Platform जैसी प्रोडक्ट सेटिंग्स में इवेंट्स सुनने के लिए चुना जा सकता है।
flows_generation और flows_template_run इवेंट्स, दोनों एक ही सब्सक्रिप्शन से सक्षम होते हैं: सुनने के लिए इवेंट्स चुनें में इमेज और वीडियो API जनरेशन या टेम्पलेट रन पूरा हुआ को चुनें, या वर्कस्पेस वेबहुक अपडेट करें को flows इवेंट पास करें। जनरेशन या रन अपना इवेंट सिर्फ़ तभी भेजता है, जब उसके क्रिएट रिक्वेस्ट में webhook फ़ील्ड शामिल हो।
वेबहुक्स को कभी भी सामान्य सेटिंग्स पेज से निष्क्रिय किया जा सकता है। अगर लगातार 10 या उससे ज़्यादा डिलीवरी विफल हों और आखिरी सफल डिलीवरी 7 दिन से ज़्यादा पहले हुई हो या कभी सफल डिलीवरी न हुई हो, तो बार-बार विफल होने वाले वेबहुक्स अपने-आप निष्क्रिय हो जाते हैं। अपने-आप निष्क्रिय हुए वेबहुक्स को सेटिंग्स पेज से फिर से सक्षम करना होगा। जिन वेबहुक्स का इस्तेमाल किसी प्रोडक्ट में नहीं हो रहा है, उन्हें हटाया जा सकता है।
फिर से कोशिश
रिक्वेस्ट विफल होने पर डिलीवरी की अपने-आप फिर से कोशिश करने के लिए, हर वेबहुक के लिए रिट्राई सक्षम किए जा सकते हैं। डिफ़ॉल्ट रूप से रिट्राई निष्क्रिय होते हैं। API से या वेबहुक सेटिंग्स में वेबहुक बनाते या अपडेट करते समय रिट्राई सक्षम करें।
रिट्राई ElevenAgents के पोस्ट-कॉल
वेबहुक्स के लिए समर्थित हैं, जिनमें ट्रांसक्रिप्शन
(post_call_transcription), ऑडियो (post_call_audio), और कॉल शुरू न होने के
(call_initiation_failure) इवेंट्स शामिल हैं।
रिट्राई शेड्यूल
जब कोई डिलीवरी प्रयास रिट्राई किए जा सकने वाले एरर के साथ विफल होता है, तो सिस्टम प्रयासों के बीच बढ़ते अंतराल के साथ 5 बार तक फिर से कोशिश करता है:
लोड को वितरित करने और थंडरिंग हर्ड समस्याओं से बचने के लिए, हर रिट्राई में थोड़ा रैंडम जिटर (अंतराल का 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) का इस्तेमाल करें।
टॉप-लेवल फ़ील्ड्स
वेबहुक पेलोड का उदाहरण
वॉइस हटाने के वेबहुक्स
वर्कस्पेस को वॉइस लाइब्रेरी से जोड़ी गई किसी शेयर की गई वॉइस के लिए ये इवेंट्स मिलते हैं, जब वॉइस का मालिक या ElevenLabs उसे वॉइस लाइब्रेरी से हटाता है।
हटाने की सूचना (voice_removal_notice)
वॉइस के लिए एक सूचना अवधि होती है। वह future_removal_timestamp तक इस्तेमाल की जा सकती है।
सूचना अवधि खत्म होने पर कोई और इवेंट नहीं भेजा जाता।
डेटा ऑब्जेक्ट का स्ट्रक्चर
हटाने की सूचना वापस ली गई (voice_removal_notice_withdrawn)
वॉइस को अब हटाने का समय तय नहीं है और वह इस्तेमाल की जा सकती है।
डेटा ऑब्जेक्ट का स्ट्रक्चर
वॉइस हटाई गई (voice_removed)
वॉइस को बिना सूचना अवधि के हटा दिया गया था और अब उसका इस्तेमाल नहीं किया जा सकता।
डेटा ऑब्जेक्ट का स्ट्रक्चर
सुझाई गई वॉइस
suggested_voices का हर आइटम दो आइटम वाली ऐरे है: वॉइस का वॉइस लाइब्रेरी शेयर URL, फिर वॉइस का नाम। सूची खाली हो सकती है।
ऑथेंटिकेशन
लिस्नर के लिए सभी इनकमिंग वेबहुक को वैलिडेट करना ज़रूरी है। वेबहुक फ़िलहाल HMAC सिग्नेचर के ज़रिए ऑथेंटिकेशन सपोर्ट करते हैं। HMAC ऑथेंटिकेशन सेट अप करने के लिए:
- वेबहुक बनाते समय जनरेट हुए शेयर किए गए सीक्रेट को सुरक्षित रूप से स्टोर करें
- SDK का इस्तेमाल करके अपने एंडपॉइंट में ElevenLabs-Signature हेडर को वेरिफ़ाई करें
JavaScript SDK में constructEvent और Python SDK में rawBody, sig_header, और secret के साथ construct_event उपलब्ध है (Python में इनके नाम payload / signature नहीं हैं)। दोनों सिग्नेचर वेरिफ़ाई करते हैं, टाइमस्टैम्प वैलिडेट करते हैं और JSON पेलोड पार्स करते हैं।
Python
JavaScript
FastAPI का इस्तेमाल करने वाले वेबहुक हैंडलर का उदाहरण: