Webhooks

अवलोकन

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

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

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

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

flows_generation और flows_template_run इवेंट्स, दोनों एक सब्सक्रिप्शन से सक्षम होते हैं: Select events to listen to के अंतर्गत Image & Video API generation or template run completed पर टिक करें, या Update workspace webhook को flows इवेंट पास करें। जनरेशन या रन अपना इवेंट तभी भेजता है, जब उसके create रिक्वेस्ट में webhook फ़ील्ड शामिल हो।

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

रिट्राई

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

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

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

लोड वितरित करने और थंडरिंग हर्ड समस्याओं से बचने के लिए हर रिट्राई में थोड़ा रैंडम जिटर (देरी का अधिकतम 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) इस्तेमाल करें।

शीर्ष-स्तरीय फ़ील्ड

उदाहरण webhook पेलोड

{
  "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 पेलोड पार्स करते हैं।

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"}