Webhooki

Omówienie

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

Konfiguracja

Webhooki można 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 platformy Agents.

Zdarzenia flows_generation i flows_template_run włącza jedna subskrypcja: w sekcji Wybierz zdarzenia do nasłuchiwania zaznacz Zakończono generowanie lub uruchomienie szablonu Image & Video API albo przekaż zdarzenie flows do aktualizacji webhooka obszaru roboczego. Generowanie lub uruchomienie wysyła zdarzenie tylko wtedy, gdy żądanie utworzenia zawiera pole webhook.

Webhooki można wyłączyć w dowolnym momencie 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 było ponad 7 dni temu lub nie nastąpiło nigdy. Automatycznie wyłączone webhooki trzeba ponownie włączyć na stronie ustawień. Webhooki można usunąć, jeśli nie są używane przez żadne produkty.

Ponowne próby

Dla każdego webhooka możesz włączyć ponowne próby, aby automatycznie ponawiać dostarczenie, gdy żądanie się nie powiedzie. Domyślnie są wyłączone. Włącz je podczas tworzenia lub aktualizowania webhooka przez API albo w ustawieniach webhooka.

Harmonogram ponownych prób

Gdy próba dostarczenia zakończy się błędem, który kwalifikuje się do ponowienia, system próbuje ponownie maksymalnie 5 razy, wydłużając przerwy między próbami:

Do każdej ponownej próby dodawane jest niewielkie losowe odchylenie (do 10% opóźnienia), aby rozłożyć obciążenie i uniknąć problemu lawinowych żądań.

Błędy kwalifikujące się do ponowienia

Nie każde niepowodzenie powoduje ponowną próbę. Kwalifikują się do niej tylko następujące błędy:

• Kody stanu 5xx (błędy serwera, takie jak 500, 502, 503, 504).
• 429 (zbyt wiele żądań).
• 408 (przekroczono limit czasu żądania).
• Błędy połączenia i przekroczenia limitu czasu żądania.

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

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, dodatkowe zadania są odrzucane, dopóki istniejące ponowienia nie zostaną przetworzone. Zapobiega to nadmiernemu zużyciu zasobów przez pojedynczy błędnie skonfigurowany webhook.

Webhooki audio mają dwa dodatkowe limity. Ładunek audio większy niż 50 MiB jest dostarczany tylko raz i nie jest ponawiany, a ponowienia audio w kolejce dla jednego webhooka nie mogą łącznie przekroczyć 400 MiB.

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ł pomyślnie dostarczony albo ostatnie udane dostarczenie było ponad 7 dni temu.

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

Integracja

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

Ładunek ponownej próby jest identyczny z pierwotną próbą dostarczenia. Odbiorcy webhooków nie mogą rozróżnić początkowego dostarczenia od ponownej próby na podstawie samego ładunku, więc zaprojektuj handler tak, aby 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 ładunek 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"
      }
    }
  }
}

Webhooki usuwania głosów

Obszar roboczy otrzymuje te zdarzenia dla udostępnionego głosu z Voice Library, który został do niego dodany, gdy właściciel głosu lub ElevenLabs usunie go z Voice Library.

Powiadomienie o usunięciu (voice_removal_notice)

Głos ma okres wypowiedzenia. Można go używać do czasu future_removal_timestamp.

Po zakończeniu okresu wypowiedzenia nie jest wysyłane kolejne zdarzenie.

Struktura obiektu danych

{
  "type": "voice_removal_notice",
  "event_timestamp": 1739537297,
  "data": {
    "voice_id": "21m00Tcm4TlvDq8ikWAM",
    "future_removal_timestamp": 1742129297,
    "suggested_voices": [
      ["https://elevenlabs.io/app/voice-lab/share/a1b2c3d4e5f6/EXAVITQu4vr4xnSDxMaL", "Sarah"]
    ]
  }
}

Wycofanie powiadomienia o usunięciu (voice_removal_notice_withdrawn)

Usunięcie głosu nie jest już zaplanowane i nadal można go używać.

Struktura obiektu danych

{
  "type": "voice_removal_notice_withdrawn",
  "event_timestamp": 1739537297,
  "data": {
    "voice_id": "21m00Tcm4TlvDq8ikWAM"
  }
}

Głos usunięty (voice_removed)

Głos został usunięty bez okresu wypowiedzenia i nie można go już używać.

Struktura obiektu danych

{
  "type": "voice_removed",
  "event_timestamp": 1739537297,
  "data": {
    "voice_id": "21m00Tcm4TlvDq8ikWAM",
    "suggested_voices": [
      ["https://elevenlabs.io/app/voice-lab/share/a1b2c3d4e5f6/EXAVITQu4vr4xnSDxMaL", "Sarah"]
    ]
  }
}

Sugerowane głosy

Każdy element suggested_voices to tablica z dwoma elementami: najpierw adres URL udostępniania głosu w Voice Library, a potem nazwa głosu. Lista może być pusta.

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