वेबहुक्स

परिचय

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

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

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

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

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

दोबारा कोशिशें

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

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

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

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

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

हर विफलता रिट्राई ट्रिगर नहीं करती। केवल निम्न HTTP स्टेटस कोड रिट्राई किए जा सकने वाले माने जाते हैं:

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

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

हर वेबहुक की क्यू सीमा

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

अपने-आप बंद होने का व्यवहार

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

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

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

इंटीग्रेशन

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

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

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

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

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