> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt. # Webhooks ## अवलोकन ElevenLabs के कुछ इवेंट्स को webhooks ट्रिगर करने के लिए कॉन्फ़िगर किया जा सकता है, जिससे बाहरी एप्लिकेशन और सिस्टम इन इवेंट्स के होने पर उन्हें प्राप्त और प्रोसेस कर सकें। फ़िलहाल समर्थित इवेंट प्रकार ये हैं: | इवेंट प्रकार | विवरण | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `post_call_transcription` | Agents Platform कॉल पूरी हो गई है और विश्लेषण पूरा हो चुका है | | `voice_removal_notice` | शेयर की गई वॉइस को हटाने का समय निर्धारित है | | `voice_removal_notice_withdrawn` | शेयर की गई वॉइस को अब हटाने का समय निर्धारित नहीं है | | `voice_removed` | शेयर की गई वॉइस हटा दी गई है और अब उपयोग नहीं की जा सकती | | `flows_generation` | एक [Image & Video जनरेशन](/docs/hi/eleven-api/guides/how-to/image-and-video/webhooks) पूरी हुई या असफल रही है | | `flows_template_run` | एक [टेम्पलेट रन](/docs/hi/eleven-api/guides/how-to/templates/run-a-template#get-the-result) पूरा हुआ या असफल रहा है | ## कॉन्फ़िगरेशन Webhooks सामान्य सेटिंग्स पेज से बनाए, निष्क्रिय और हटाए जा सकते हैं। [वर्कस्पेसेस](/docs/hi/overview/administration/workspaces/overview) के यूज़र्स के लिए, सिर्फ़ वर्कस्पेस एडमिन ही वर्कस्पेस के webhooks कॉन्फ़िगर कर सकते हैं। ![HMAC webhook कॉन्फ़िगरेशन](/docs/_fern-img/9ea298daac1c64eb43c802a12f7824e83accca44ba2edd1d01a39bcd62c0b9d6.webp) बनने के बाद, webhook को [Agents Platform](/docs/hi/eleven-agents/workflows/post-call-webhooks) जैसी प्रोडक्ट सेटिंग्स में इवेंट्स सुनने के लिए चुना जा सकता है। `flows_generation` और `flows_template_run` इवेंट्स, दोनों एक सब्सक्रिप्शन से सक्षम होते हैं: **Select events to listen to** के अंतर्गत **Image & Video API generation or template run completed** पर टिक करें, या [Update workspace webhook](/docs/hi/api-reference/webhooks/update) को `flows` इवेंट पास करें। जनरेशन या रन अपना इवेंट तभी भेजता है, जब उसके create रिक्वेस्ट में `webhook` फ़ील्ड शामिल हो। Webhooks को सामान्य सेटिंग्स पेज से कभी भी निष्क्रिय किया जा सकता है। यदि लगातार 10 या अधिक विफलताएं हों और आख़िरी सफल डिलीवरी 7 दिन से अधिक पहले हुई हो या कभी सफल डिलीवरी न हुई हो, तो बार-बार विफल होने वाले webhooks अपने-आप निष्क्रिय हो जाते हैं। अपने-आप निष्क्रिय हुए webhooks को सेटिंग्स पेज से फिर सक्षम करना होगा। अगर webhooks किसी प्रोडक्ट में इस्तेमाल नहीं हो रहे हैं, तो उन्हें हटाया जा सकता है। ## रिट्राई किसी रिक्वेस्ट के असफल होने पर डिलीवरी फिर से आज़माने के लिए, हर webhook के लिए webhook रिट्राई सक्षम किए जा सकते हैं। रिट्राई डिफ़ॉल्ट रूप से निष्क्रिय होते हैं। [API](/docs/hi/api-reference/webhooks/create) के ज़रिए या webhook सेटिंग्स में webhook बनाते या अपडेट करते समय रिट्राई सक्षम करें। > **Note** > > रिट्राई ElevenAgents [पोस्ट-कॉल webhooks](/docs/hi/eleven-agents/workflows/post-call-webhooks) के लिए समर्थित हैं, जिनमें ट्रांसक्रिप्शन > (`post_call_transcription`), ऑडियो (`post_call_audio`), और कॉल शुरू होने की विफलता > (`call_initiation_failure`) इवेंट्स शामिल हैं। ### रिट्राई शेड्यूल जब डिलीवरी का प्रयास रिट्राई किए जा सकने वाले एरर से असफल होता है, तो सिस्टम प्रयासों के बीच बढ़ती देरी के साथ अधिकतम 5 बार रिट्राई करता है: | प्रयास | देरी | | ------ | -------- | | 1 | तुरंत | | 2 | 30 सेकंड | | 3 | 2 मिनट | | 4 | 8 मिनट | | 5 | 30 मिनट | लोड वितरित करने और थंडरिंग हर्ड समस्याओं से बचने के लिए हर रिट्राई में थोड़ा रैंडम जिटर (देरी का अधिकतम 10%) जोड़ा जाता है। ### रिट्राई किए जा सकने वाले एरर हर विफलता रिट्राई ट्रिगर नहीं करती। सिर्फ़ ये विफलताएं रिट्राई की जा सकती हैं: * `5xx` स्टेटस कोड (सर्वर एरर, जैसे 500, 502, 503, 504)। * `429` (बहुत अधिक रिक्वेस्ट)। * `408` (रिक्वेस्ट टाइमआउट)। * कनेक्शन एरर और रिक्वेस्ट टाइमआउट। `4xx` रेंज के रिक्वेस्ट एरर (जैसे 400, 401, 403, 404) का रिट्राई **नहीं** किया जाता, क्योंकि वे आम तौर पर कॉन्फ़िगरेशन समस्या बताते हैं, जिसके लिए मैन्युअल सुधार चाहिए। ### हर webhook की क्यू सीमाएं हर webhook में अधिकतम 100 लंबित रिट्राई जॉब हो सकते हैं। अगर webhook में 100 से अधिक रिट्राई क्यू में जमा हो जाएं, तो मौजूदा रिट्राई प्रोसेस होने तक अतिरिक्त जॉब हटा दिए जाते हैं। इससे गलत कॉन्फ़िगर किया गया कोई एक webhook बहुत ज़्यादा संसाधन इस्तेमाल नहीं करता। ऑडियो webhooks की दो अतिरिक्त सीमाएं हैं। 50 MiB से बड़ा ऑडियो पेलोड एक बार डिलीवर किया जाता है और उसका रिट्राई नहीं होता, तथा किसी एक webhook के क्यू में मौजूद ऑडियो रिट्राई कुल मिलाकर 400 MiB से अधिक नहीं हो सकते। ### अपने-आप निष्क्रिय होने का व्यवहार सिस्टम हर webhook की लगातार डिलीवरी विफलताओं को ट्रैक करता है। नीचे दी गई दोनों शर्तें पूरी होने पर webhook अपने-आप निष्क्रिय हो जाता है: * लगातार 10 या अधिक डिलीवरी विफलताएं हुई हों। * webhook की कभी सफल डिलीवरी न हुई हो, या आख़िरी सफल डिलीवरी 7 दिन से अधिक पहले हुई हो। जब कोई webhook अपने-आप निष्क्रिय होता है, तो वर्कस्पेस एडमिन को ईमेल सूचना मिलती है। डिलीवरी फिर शुरू करने से पहले webhook को सेटिंग्स पेज से मैन्युअली फिर सक्षम करना होगा। ## इंटीग्रेशन Webhooks के साथ इंटीग्रेट करने के लिए, POST रिक्वेस्ट के रूप में webhook इवेंट डेटा पाने के लिए एक एंडपॉइंट हैंडलर बनाएं। हस्ताक्षर सत्यापित करने के बाद, सफल प्राप्ति बताने के लिए हैंडलर को तुरंत HTTP 200 लौटाना चाहिए। लगातार सफल रिस्पॉन्स न लौटाने पर webhook अपने-आप निष्क्रिय हो सकता है। रिट्राई पेलोड मूल डिलीवरी प्रयास जैसा ही होता है। Webhook उपभोक्ता सिर्फ़ पेलोड से शुरुआती डिलीवरी और रिट्राई में अंतर नहीं कर सकते, इसलिए अपने हैंडलर को **idempotent** बनाएं — एक ही इवेंट को कई बार प्रोसेस करने पर एक ही परिणाम मिलना चाहिए। ज़रूरत हो तो इवेंट्स को डुप्लिकेट हटाने के लिए `event_timestamp` और इवेंट-विशिष्ट आइडेंटिफ़ायर्स (जैसे `conversation_id`) इस्तेमाल करें। ### शीर्ष-स्तरीय फ़ील्ड | फ़ील्ड | प्रकार | विवरण | | ----------------- | ------ | --------------- | | `type` | string | इवेंट का प्रकार | | `data` | object | इवेंट का डेटा | | `event_timestamp` | string | यह इवेंट कब हुआ | ## उदाहरण webhook पेलोड ```json { "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" } } } } ``` ## ऑथेंटिकेशन लिस्नर के लिए सभी इनकमिंग वेबहुक को वैलिडेट करना ज़रूरी है। वेबहुक फ़िलहाल HMAC सिग्नेचर के ज़रिए ऑथेंटिकेशन सपोर्ट करते हैं। HMAC ऑथेंटिकेशन सेट अप करने के लिए: * वेबहुक बनाते समय जनरेट हुए शेयर किए गए सीक्रेट को सुरक्षित रूप से स्टोर करें * SDK का इस्तेमाल करके अपने एंडपॉइंट में ElevenLabs-Signature हेडर को वेरिफ़ाई करें JavaScript SDK में `constructEvent` और Python SDK में **`rawBody`**, **`sig_header`**, और **`secret`** के साथ `construct_event` उपलब्ध है (Python में इनके नाम `payload` / `signature` नहीं हैं)। दोनों सिग्नेचर वेरिफ़ाई करते हैं, टाइमस्टैम्प वैलिडेट करते हैं और JSON पेलोड पार्स करते हैं। #### Python FastAPI का इस्तेमाल करने वाले वेबहुक हैंडलर का उदाहरण: ```python 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"} ``` #### JavaScript #### Express Express का इस्तेमाल करने वाले वेबहुक हैंडलर का उदाहरण: ```javascript import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js'; import express from 'express'; const app = express(); const elevenlabs = new ElevenLabsClient(); const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET; // Use express.text() to preserve raw body for signature verification app.post('/webhook', express.text({ type: 'application/json' }), async (req, res) => { const signature = req.headers['elevenlabs-signature']; const payload = req.body; // Raw string body let event; try { event = await elevenlabs.webhooks.constructEvent(payload, signature, WEBHOOK_SECRET); } catch (error) { return res.status(401).json({ error: 'Invalid signature' }); } // Process the webhook event if (event.type === 'post_call_transcription') { console.log('Received transcription:', event.data); } res.status(200).json({ received: true }); }); ``` #### Next.js Next.js API रूट का इस्तेमाल करने वाले वेबहुक हैंडलर का उदाहरण: **`app/api/webhook/route.ts`** ```typescript app/api/webhook/route.ts import { NextResponse } from 'next/server'; import type { NextRequest } from 'next/server'; import { ElevenLabsClient } from '@elevenlabs/elevenlabs-js'; const elevenlabs = new ElevenLabsClient(); const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET; export async function POST(req: NextRequest) { const body = await req.text(); const signature = req.headers.get('elevenlabs-signature'); let event; try { event = await elevenlabs.webhooks.constructEvent(body, signature, WEBHOOK_SECRET); } catch (error) { return NextResponse.json({ error: 'Invalid signature' }, { status: 401 }); } // Process the webhook event if (event.type === 'post_call_transcription') { console.log('Received transcription:', event.data); } return NextResponse.json({ received: true }, { status: 200 }); } ```