Koncové body webhookov

Spravujte viacero adries URL webhookov s tajnými kľúčmi a filtrami udalostí pre jednotlivé koncové body.

Systém webhookov založený na koncových bodoch vám umožňuje zaregistrovať viacero cieľov pre organizáciu, pričom každý má vlastné tajomstvo, vlastný stav a vlastné predplatné podmnožiny typov udalostí. Toto je odporúčaný model pre všetky nové integrácie.

Porovnajte so starším webhookom s jednou URL, ktorý je zachovaný kvôli spätnej kompatibilite, ale podporuje iba jednu URL pre organizáciu.

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",
  "created_at": "2026-04-20T18:24:10.113Z",
  "updated_at": "2026-04-20T18:24:10.113Z"
}

Platné typy udalostí#

events sa overuje voči tejto presnej množine — hodnoty mimo zoznamu vrátia 400. Tvar údajov každého typu nájdete v katalógu udalostí.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• call.graded, call.data_extracted
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated nemá kontext hlasového agenta a doručuje sa iba do koncových bodov platných pre celú organizáciu.

voice.ready a voice.failed nemožno vybrať explicitne. Ak ich chcete prijímať, vytvorte koncový bod platný pre celú organizáciu s events: []. Prázdny zoznam udalostí prijíma každú podporovanú udalosť okrem telephony.turn a web.turn, ktoré je nutné vybrať explicitne.

Stavy koncových bodov#

• active — doručovanie prebieha normálne.
• disabled — manuálne pozastavené prostredníctvom PATCH. Neodosielajú sa žiadne požiadavky. Stav koncového bodu disabled nikdy nemeníme; rozhodnutie prepnúť ho späť na active je vždy na vás.
• failing — nastaví sa automaticky, keď doručenie do koncového bodu vyčerpá celý harmonogram opakovaných pokusov (8 pokusov počas 24 hodín) bez získania odpovede 2xx. Koncový bod v stave zlyhania neprijíma žiadnu ďalšiu prevádzku. Po oprave koncového bodu zmeňte jeho stav pomocou PATCH späť na active; doručovania, ktorých harmonogram opakovaných pokusov ešte nevypršal, budú pokračovať tam, kde skončili.

Zoznam koncových bodov#

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

Vráti pole objektov koncových bodov. Ak chcete vrátiť iba koncové body obmedzené na daného hlasového agenta, pridajte ?agent_id=42.

Koncové body obmedzené na hlasového agenta#

Koncové body platné pre celú organizáciu prijímajú každú zodpovedajúcu udalosť. Koncový bod s agent_id prijíma iba zodpovedajúce udalosti pre hovory spracované daným hlasovým agentom; udalosti bez kontextu hlasového agenta, napríklad alert.triggered, sa k nemu nikdy nedostanú. Tieto koncové body môžete vytvárať a spravovať aj v sekcii Webhooky v nástroji na tvorbu hlasových agentov.

Vytvorte koncový bod#

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

Polia požiadavky#

Vráti 201 Created s objektom koncového bodu a dodatočným poľom najvyššej úrovne secret, ktoré obsahuje nespracovaný podpisový kľúč — 48-znakový hexadecimálny reťazec:

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

Aktualizujte koncový bod#

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

Vráti 200 OK s aktualizovaným objektom koncového bodu.

Odoslanie testovacej doručovacej požiadavky#

Odošlite syntetickú udalosť webhook.test na jeden endpoint pomocou štandardného procesu doručovania vrátane kanonickej serializácie JSON, X-ThunderPhone-Signature, zaznamenania doručovania a správy opakovaných pokusov. Test je zameraný na vybraný endpoint bez ohľadu na jeho filter events.

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

Endpoint dostane obálku podobnú tejto:

{
  "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 po prvom pokuse vráti 200 OK, aj keď cieľ vráti chybu. Výsledok doručenia skontrolujte v poliach 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á udalosť a nemožno ju pridať do odberu events endpointu. Ak prvý pokus zlyhá, doručenie sa riadi rovnakým plánom opakovaných pokusov ako doručovanie bežných udalostí.

Ak chcete nakonfigurovať spúšťač podľa tvaru skutočnej udalosti, odovzdajte voliteľný parameter event_type. Doručenie je stále syntetické a obsahuje "sample": true; vzorky súvisiace s hovormi 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 prijíma ľubovoľnú hodnotu zo zoznamu Platné typy udalostí. Jeho vynechaním zachováte všeobecné správanie webhook.test.

Odstránenie endpointu#

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

Vráti 204 No Content. Doručovanie na URL sa okamžite zastaví; prebiehajúce opakované pokusy sa zrušia.

Ladenie doručení#

Skôr než usúdite, že webhook nebol odoslaný, skontrolujte GET /v1/developer/webhook-deliveries. Zobrazuje nedávne pokusy z oboch webhookových systémov vrátane ID hovoru, pôvodu URL, stavu HTTP, počtu pokusov, kategórie chýb zo zoznamu povolených hodnôt a času ďalšieho opakovania. Nikdy nevracia payload udalosti, prepis, uložený text chyby, telo odpovede ani cestu URL.

Rovnakú nedávnu históriu si môžete zobraziť aj v Agenti → vyberte agenta → Webhooky → Nedávne doručenia. Riadky zobrazujú označenie endpointu a pôvod URL použitý pri najnovšom pokuse. Ide o prevádzkový stav, nie o nemenný auditný záznam: odstránením endpointu sa odstránia aj jeho riadky doručení.

Pri chybe n8n 404 najprv potvrďte, že je pracovný postup aktívny, prijíma POST a používa produkčnú URL webhooku, nie testovaciu URL. Kód 401 alebo 403 naznačuje problém s autentifikáciou alebo overením podpisu; časové limity naznačujú latenciu alebo dostupnosť cieľa; chyby TLS naznačujú problém s reťazcom certifikátov, názvom hostiteľa alebo platnosťou.

Súvisiace#