Dokumentace

Webhooks

Dokumentace

Webhooky jsou způsob, jak platforma notifikuje vaše systémy, když se něco stane — hovor začal, session skončila, cíl byl dosažen. Přihlásíte se URL; platforma na tuto URL POST-ne JSON payload, když se event spustí.

Tato stránka popisuje eventy, kontrakt doručení a schéma podepisování. Subscriptions se spravují v záložce projektu Webhooks.

Katalog eventů

Dnes se dodává pět eventů:

  • session.started — spustí se, když se hovor spojí a agent začne mluvit. Nese session id, scenario id, směr (inbound/outbound), telefonní číslo volajícího (maskované, např. +3412•••789 — plné číslo je dostupné přes GET /v1/sessions/{id}) a zda jde o test session.
  • session.ended — spustí se, když hovor skončí. Nese session id, finální status (completed / abandoned / failed), délku a zda byl cíl dosažen. Úplný záznam session — přepis, sloty, outcome — stáhnete přes GET /v1/sessions/{id}.
  • session.failed — spustí se, když session skončila chybou. Nese session id a důvod selhání.
  • goal.achieved — spustí se ve chvíli, kdy agent dosáhne cíle scénáře, uprostřed hovoru, jednou za session. Payload zahrnuje definici cíle a hodnoty slotů zachycené do toho bodu. Použijte pro navazující side effects, které chcete ihned, ne na konci session.
  • intent.classified — spustí se, když intent classifier vybere scénář na multi-scenario projektu. Užitečné pro audit a měření přesnosti routování.

Webhooky dnes pokrývají hlasové session; eventy pro messenger konverzace a dokončení dávky jsou na roadmapě.

Přihlášení (subscribe)

V záložce projektu Webhooks vytvořte subscription:

  • URL — kam přijímáte POSTy. Musí být HTTPS.
  • Events — vyberte z katalogu. Jeden event, několik, nebo všechny.

Platforma při vytvoření jednou ukáže signing secret — zkopírujte ho do prostředí. Později ho už nelze získat; můžete rotovat, což secret okamžitě nahradí (nejprve aktualizujte endpoint, pak rotujte).

Můžete mít až 10 subscriptions na projekt.

Formát payloadu

Každý payload je JSON a sdílí tuto obálku:

{
  "event": "session.ended",
  "deliveryId": "5b2c4f8a-…",
  "ts": "2026-05-13T18:42:11Z",
  "tenantId": "…",
  "projectId": "…",
  "data": { … }
}

Schéma objektu data je specifické pro event. Doručení je at-least-once a deliveryId je stabilní napříč retry stejného eventu — použijte ho pro idempotenci na vaší straně.

Podepisování

Každý request nese tyto headery:

  • x-avp-signature — sha256=<hex>, kde hex hodnota je HMAC-SHA256 raw request body, klíčovaná signing secretem vaší subscription.
  • x-avp-event — typ eventu, abyste mohli routovat před parsováním.
  • x-avp-timestamp — kdy bylo doručení odesláno.
  • x-avp-subscription-id — ke které subscription toto doručení patří.
  • x-avp-delivery-id — stejná hodnota jako deliveryId v body.

Ověřujte signaturu na každém requestu: spočítejte HMAC raw body se secret a porovnejte s headerem. Povinné je porovnání stringů v constant-time — naivní == je napadnutelné timing attackem. Cokoli, co nesedí, odmítněte.

Retry a spolehlivost

  • At-least-once doručení: stejný event může dorazit více než jednou. Pro idempotenci použijte deliveryId.
  • Timeout: 10 sekund. Pokud endpoint trvá déle, doručení se počítá jako neúspěšné.
  • Retry politika: první pokus je okamžitý, pak 5 retry s rostoucím backoffem (1 min → 5 min → 15 min → 1 h → 6 h). Po posledním retry se doručení zahodí a zaloguje.
  • Auto-disable: pokud subscription trvale selhává (50+ zahozených doručení do 24 hodin), platforma ji vypne. Znovu ji zapnete v záložce Webhooks po opravě endpointu.

Záložka Webhooks ukazuje delivery log pro každou subscription — každý pokus, status odpovědi, latenci, úryvek odpovědi vašeho endpointu. Je tu také akce send test delivery, abyste endpoint ověřili dřív, než na něj dorazí reálný traffic.

Inbound webhooks (opačný směr)

Můžete také pushovat eventy do živých konverzací. Vytvořte v projektu inbound webhook se jménem; platforma vám dá URL a dedikovaný signing secret (zobrazený jednou).

POST /v1/projects/{project_id}/webhooks/{name}
x-avp-signature: sha256=<hex-hmac-of-raw-body>
Content-Type: application/json

Podepište raw body secretem inbound webhooku, stejným schématem HMAC-SHA256 jako u outbound doručení. Body se doručí každé aktivní session projektu v okamžiku příchodu requestu jako intercept event on_webhook_received; skript připojený k tomuto eventu payload přečte a rozhodne, co udělat — uprostřed hovoru oznámit agentovi, že objednávka byla odeslána, poslat změnu ceny do živé konzultace, spustit tool call zvenku.

Limity: 25 jmen inbound webhooků na projekt. Requesty na neexistující jméno vrátí 404; session bez handleru on_webhook_received event ignorují.