Koncové body webhooků

Spravujte více adres URL webhooků s tajnými klíči a filtry událostí pro jednotlivé koncové body.

Systém webhooků založený na koncových bodech vám umožňuje zaregistrovat více cílů pro každou organizaci, přičemž každý má vlastní tajný klíč, vlastní stav a vlastní odběr podmnožiny typů událostí. Toto je doporučený model pro všechny nové integrace.

Porovnejte jej se starším webhookem s jednou adresou URL, který je zachován kvůli zpětné kompatibilitě, ale podporuje pouze jednu adresu URL na organizaci.

Koncové body#

Objekt koncového bodu#

{
  "id": "c4d5e6f7-...",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Platné typy událostí#

events se ověřuje podle přesně této sady — hodnoty mimo seznam vrátí 400. Tvar datové části jednotlivých typů najdete v katalogu událostí.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (rezervováno; zatím se nevysílá)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated nemá kontext agenta a doručuje se pouze koncovým bodům pro celou organizaci.

voice.ready a voice.failed nelze vybrat explicitně. Chcete-li je přijímat, vytvořte koncový bod pro celou organizaci s events: []. Prázdný seznam událostí přijímá všechny podporované události kromě telephony.turn a web.turn, které musí být vybrány explicitně.

Stavy koncového bodu#

• active — doručování probíhá normálně.
• disabled — ručně pozastaveno pomocí PATCH. Neodesílají se žádné požadavky. Stav endpointu disabled nikdy neměníme; o jeho přepnutí zpět na active vždy rozhodujete vy.
• failing — nastaví se automaticky, když doručování do endpointu vyčerpá celý plán opakování (8 pokusů během 24 hodin), aniž by kdy obdrželo odpověď 2xx. Endpoint ve stavu selhání nepřijímá žádný další provoz. Když k tomu dojde, odešleme e-mail vlastníkům a správcům vaší organizace a řídicí panel zobrazí pozastavený endpoint s tlačítkem Znovu aktivovat. Po opravě endpointu pomocí PATCH změňte jeho stav zpět na active; doručování, jehož plán opakování ještě nevypršel, bude pokračovat tam, kde skončilo.

Výpis koncových bodů#

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Vrací pole objektů koncových bodů. Předejte ?agent_id=42, chcete-li vrátit pouze koncové body omezené na tohoto agenta.

Koncové body omezené na agenta#

Koncové body pro celou organizaci přijímají všechny odpovídající události. Koncový bod s agent_id přijímá pouze odpovídající události pro hovory vyřízené daným agentem; události bez kontextu agenta, jako například alert.triggered, jej nikdy nedosáhnou. Tyto koncové body můžete také vytvářet a spravovat v sekci Webhooky editoru agenta.

Vytvoření endpointu#

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call events",
    "url":    "https://example.com/thunderphone/hook",
    "events": ["telephony.incoming", "telephony.complete"]
  }'

result = requests.post(
    "https://api.thunderphone.com/v1/developer/webhook-endpoints",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "label":  "Production — Call events",
        "url":    "https://example.com/thunderphone/hook",
        "events": ["telephony.incoming", "telephony.complete"],
    },
).json()
secret = result["secret"]
endpoint_id = result["id"]

Pole požadavku#

Vrací 201 Created s objektem endpointu a dalším polem secret na nejvyšší úrovni obsahujícím nezpracovaný podpisový klíč — 48znakový hexadecimální řetězec:

{
  "id": "c4d5e6f7-…",
  "label": "Production — Call events",
  "url": "https://example.com/thunderphone/hook",
  "events": ["telephony.incoming", "telephony.complete"],
  "status": "active",
  "secret_hint": "a1b2…9f0e",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z",
  "secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}

Aktualizace endpointu#

curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label":  "Production — Call + Grade events",
    "events": ["telephony.incoming", "telephony.complete", "call.graded"]
  }'

Vrací 200 OK s aktualizovaným objektem endpointu.

Obnovení podpisového tajemství#

Nahraďte podpisové tajemství endpointu, například pokud se ztratilo nebo mohlo uniknout. Pro endpoint vázaný na agenta můžete také použít dashboard: otevřete sekci Webhooky agenta a u endpointu vyberte Znovu vygenerovat tajemství. Endpointy platné pro celou organizaci se obnovují prostřednictvím API.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Vrací 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

Odeslání testovacího doručení#

Odešlete syntetickou událost webhook.test do jednoho endpointu pomocí standardního procesu doručení, včetně kanonické serializace JSON, obou hlaviček podpisu, záznamu o doručení a evidence opakovaných pokusů. Test cílí na vybraný endpoint bez ohledu na jeho filtr events.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Koncový bod obdrží obálku podobnou této:

{
  "data": {
    "message": "ThunderPhone webhook test",
    "sent_at": "2026-07-17T20:12:34.567890+00:00"
  },
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "type": "webhook.test"
}

API vrátí 200 OK po prvním pokusu, i když cíl vrátí chybu. Výsledek doručení zjistíte kontrolou success, status, response_code a error:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test je syntetická událost a nelze ji přidat k odběru events koncového bodu. Pokud první pokus selže, ThunderPhone jej přibližně o minutu později jednou zopakuje a poté se zastaví; doručení pak zobrazí status: "failed" v části Ladění doručení. Testovací doručení nikdy neoznačí koncový bod jako failing.

Chcete-li nakonfigurovat spouštěč pro skutečnou strukturu události, předejte volitelný parametr event_type. Doručení je stále syntetické a obsahuje "sample": true; ukázky související s hovory používají call_id: 0 a agent_id: 0.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type přijímá libovolnou hodnotu z Platných typů událostí. Jeho vynechání zachová obecné chování webhook.test.

Odstranění koncového bodu#

curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Vrátí 204 No Content. Doručování na URL se okamžitě zastaví; probíhající opakované pokusy jsou zrušeny.

Ladění doručení#

Než dospějete k závěru, že webhook nebyl odeslán, zkontrolujte GET /v1/developer/webhook-deliveries. Zobrazuje nedávné pokusy z obou systémů webhooků, včetně ID hovoru, původu URL, stavu HTTP, počtu pokusů, kategorie povoleného selhání a času dalšího opakovaného pokusu. Nikdy nevrací datovou část události, přepis, uložený text chyby, tělo odpovědi ani cestu URL.

Stejnou nedávnou historii můžete zobrazit také v části Agenti → vyberte agenta → Webhooky → Poslední doručení. Řádky zobrazují štítek koncového bodu a původ URL použitý při posledním pokusu. Jde o provozní stav, nikoli neměnný auditní záznam: odstraněním koncového bodu se odstraní také jeho řádky doručení.

U chyby n8n 404 nejprve ověřte, že je pracovní postup aktivní, přijímá POST a používá produkční URL webhooku namísto testovací URL. Chyba 401 nebo 403 ukazuje na ověřování nebo validaci podpisu; časové limity ukazují na latenci nebo dostupnost cíle; chyby TLS ukazují na řetězec certifikátů, název hostitele nebo platnost.

Související#