Webhooki

Omówienie

Niektóre zdarzenia w ElevenLabs można skonfigurować tak, by wywoływały webhooki, dzięki czemu zewnętrzne aplikacje i systemy mogą odbierać oraz przetwarzać je na bieżąco. Obecnie obsługiwane są następujące typy zdarzeń:

Konfiguracja

Webhooki możesz tworzyć, wyłączać i usuwać na stronie ustawień ogólnych. W przypadku użytkowników obszarów roboczych webhooki dla obszaru roboczego mogą konfigurować tylko jego administratorzy.

Po utworzeniu webhook można wybrać do nasłuchiwania zdarzeń w ustawieniach produktu, na przykład Agents Platform.

Webhooki możesz w każdej chwili wyłączyć na stronie ustawień ogólnych. Webhooki, które wielokrotnie zawodzą, są automatycznie wyłączane, jeśli wystąpiło co najmniej 10 kolejnych błędów, a ostatnie udane dostarczenie miało miejsce ponad 7 dni temu lub nigdy nie nastąpiło. Automatycznie wyłączone webhooki trzeba ponownie włączyć na stronie ustawień. Webhooki można usunąć, jeśli nie są używane przez żadne produkty.

Ponowienia

Dla każdego webhooka możesz włączyć ponowienia, aby automatycznie spróbować dostarczyć żądanie ponownie po błędzie. Ponowienia są domyślnie wyłączone. Włącz je podczas tworzenia lub aktualizacji webhooka przez API albo w ustawieniach webhooka.

Harmonogram ponowień

Gdy próba dostarczenia zakończy się błędem, który można ponowić, system podejmie do 5 kolejnych prób z rosnącymi odstępami:

Do każdego ponowienia dodawane jest niewielkie losowe odchylenie (do 10% opóźnienia), aby rozłożyć obciążenie i uniknąć problemów typu thundering herd.

Błędy kwalifikujące się do ponowienia

Nie wszystkie błędy uruchamiają ponowienie. Za kwalifikujące się uznawane są tylko poniższe kody statusu HTTP:

• Kody statusu 5xx (błędy serwera, takie jak 500, 502, 503, 504).
• 429 (Too Many Requests).
• 408 (Request Timeout).

Błędy żądań z zakresu 4xx (takie jak 400, 401, 403, 404) nie są ponawiane, ponieważ zwykle wskazują na problem z konfiguracją, który wymaga ręcznej poprawy.

Limity kolejki dla webhooka

Każdy webhook może mieć maksymalnie 100 oczekujących zadań ponowienia. Jeśli webhook zgromadzi ponad 100 ponowień w kolejce, kolejne zadania będą odrzucane, dopóki istniejące ponowienia nie zostaną przetworzone. Zapobiega to nadmiernemu zużyciu zasobów przez pojedynczy źle skonfigurowany webhook.

Automatyczne wyłączanie

System śledzi kolejne błędy dostarczania dla każdego webhooka. Webhook jest automatycznie wyłączany, gdy spełnione są oba poniższe warunki:

• Wystąpiło co najmniej 10 kolejnych błędów dostarczania.
• Webhook nigdy nie został dostarczony pomyślnie albo ostatnie udane dostarczenie nastąpiło ponad 7 dni temu.

Gdy webhook zostanie automatycznie wyłączony, administratorzy obszaru roboczego otrzymają powiadomienie e-mail. Zanim webhook wznowi dostarczanie, trzeba go ręcznie włączyć ponownie na stronie ustawień.

Integracja

Aby zintegrować się z webhookami, utwórz handler endpointu, który będzie odbierać dane zdarzeń webhooka jako żądania POST. Po sprawdzeniu podpisu handler powinien szybko zwrócić HTTP 200, aby potwierdzić pomyślny odbiór. Powtarzający się brak odpowiedzi potwierdzającej sukces może spowodować automatyczne wyłączenie webhooka.

Payload ponowienia jest identyczny jak w pierwotnej próbie dostarczenia. Odbiorcy webhooków nie mogą rozróżnić pierwszego dostarczenia od ponowienia na podstawie samego payloadu, dlatego zaprojektuj handler tak, by był idempotentny — wielokrotne przetworzenie tego samego zdarzenia powinno dawać ten sam wynik. W razie potrzeby użyj event_timestamp i identyfikatorów specyficznych dla zdarzenia (takich jak conversation_id), aby usuwać duplikaty zdarzeń.

Pola najwyższego poziomu

Przykładowy payload webhooka

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

Uwierzytelnianie

Ważne, by odbiornik weryfikował wszystkie przychodzące webhooki. Webhooki obecnie obsługują uwierzytelnianie za pomocą podpisów HMAC. Aby skonfigurować uwierzytelnianie HMAC:

• Bezpiecznie przechowuj współdzielony sekret wygenerowany podczas tworzenia webhooka
• Zweryfikuj nagłówek ElevenLabs-Signature w swoim endpointzie za pomocą SDK

SDK JavaScript udostępnia constructEvent, a SDK Python construct_event z parametrami rawBody, sig_header i secret (w Pythonie nie nazywają się one payload / signature). Oba weryfikują podpis, sprawdzają znacznik czasu i parsują dane 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"}