Webhook krajnje točke

Upravljajte s više URL-ova webhooka uz tajne ključeve i filtre događaja za svaku krajnju točku.

Sustav webhookova temeljen na krajnjim točkama omogućuje vam registraciju više odredišta po organizaciji, pri čemu svako ima vlastitu tajnu, vlastiti status i vlastitu pretplatu na podskup vrsta događaja. Ovo je preporučeni model za sve nove integracije.

Usporedite sa zastarjelim webhookom s jednim URL-om, koji je zadržan radi povratne kompatibilnosti, ali podržava samo jedan URL po organizaciji.

Krajnje točke#

Objekt krajnje točke#

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

Važeće vrste događaja#

events se provjerava prema ovom točnom skupu — vrijednosti izvan popisa vraćaju 400. Pogledajte Katalog događaja za strukturu korisnog sadržaja svake vrste.

• 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 nema kontekst agenta i isporučuje se samo krajnjim točkama za cijelu organizaciju.

voice.ready i voice.failed nije moguće eksplicitno odabrati. Da biste ih primali, izradite krajnju točku za cijelu organizaciju s events: []. Prazan popis događaja prima svaki podržani događaj osim telephony.turn i web.turn, koje morate eksplicitno odabrati.

Statusi krajnjih točaka#

• active — isporuke se odvijaju uobičajeno.
• disabled — ručno pauzirano putem PATCH. Zahtjevi se ne šalju. Nikada ne mijenjamo status krajnje točke disabled; odluka o vraćanju na active uvijek je vaša.
• failing — postavlja se automatski kada isporuka krajnjoj točki iscrpi cijeli raspored ponovnih pokušaja (8 pokušaja tijekom 24 sata), a da nikada ne dobije 2xx odgovor. Krajnja točka sa statusom failing ne prima daljnji promet. Nakon što popravite krajnju točku, putem PATCH vratite njezin status na active; isporuke čiji raspored ponovnih pokušaja još nije istekao nastavljaju ondje gdje su stale.

Popis krajnjih točaka#

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

Vraća niz objekata krajnjih točaka. Proslijedite ?agent_id=42 kako biste vratili samo krajnje točke ograničene na tog agenta.

Krajnje točke ograničene na agenta#

Krajnje točke za cijelu organizaciju primaju svaki odgovarajući događaj. Krajnja točka s agent_id prima samo odgovarajuće događaje za pozive kojima upravlja taj agent; događaji bez konteksta agenta, kao što je alert.triggered, nikada je ne dosežu. Te krajnje točke možete i izraditi te upravljati njima iz odjeljka Webhookovi u alatu za izradu agenta.

Izrada krajnje točke#

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

Polja zahtjeva#

Vraća 201 Created s ažuriranim objektom krajnje točke i dodatnim poljem secret na najvišoj razini koje sadržava neobrađeni ključ za potpisivanje — heksadecimalni niz od 48 znakova:

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

Ažuriranje krajnje točke#

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

Vraća 200 OK s ažuriranim objektom krajnje točke.

Pošaljite testnu isporuku#

Pošaljite sintetički događaj webhook.test na jednu krajnju točku putem uobičajenog kanala isporuke, uključujući kanonsku JSON serijalizaciju, X-ThunderPhone-Signature, bilježenje isporuke i evidentiranje ponovnih pokušaja. Test cilja odabranu krajnju točku bez obzira na njezin filtar events.

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

Krajnja točka prima omotnicu poput ove:

{
  "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 vraća 200 OK nakon prvog pokušaja, čak i ako odredište vrati pogrešku. Provjerite success, status, response_code i error za ishod isporuke:

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

webhook.test je sintetički i ne može se dodati pretplati krajnje točke na events. Ako prvi pokušaj ne uspije, isporuka slijedi isti raspored ponovnih pokušaja kao i uobičajene isporuke događaja.

Za konfiguriranje okidača prema stvarnom obliku događaja proslijedite neobavezni event_type. Isporuka je i dalje sintetička te sadrži "sample": true; uzorci povezani s pozivima koriste call_id: 0 i 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 prihvaća bilo koju vrijednost iz odjeljka Valjane vrste događaja. Izostavljanje zadržava općenito ponašanje webhook.test.

Izbrišite krajnju točku#

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

Vraća 204 No Content. Isporuka na URL odmah prestaje; ponovni pokušaji u tijeku se prekidaju.

Otklanjanje pogrešaka pri isporuci#

Prije nego što zaključite da webhook nije poslan, provjerite GET /v1/developer/webhook-deliveries. Prikazuje nedavne pokušaje iz oba webhook sustava, uključujući ID poziva, ishodište URL-a, HTTP status, broj pokušaja, kategoriju neuspjeha s popisa dopuštenih i vrijeme sljedećeg ponovnog pokušaja. Nikada ne vraća podatkovni sadržaj događaja, transkript, pohranjeni tekst pogreške, tijelo odgovora ni putanju URL-a.

Istu nedavnu povijest možete vidjeti i u Agenti → odaberite agenta → Webhookovi → Nedavne isporuke. Redovi prikazuju oznaku krajnje točke i ishodište URL-a koje je upotrijebio najnoviji pokušaj. Ovo je operativno stanje, a ne nepromjenjivi zapis revizije: brisanje krajnje točke također briše njezine retke isporuke.

Za n8n 404 najprije potvrdite da je tijek rada aktivan, prihvaća POST i koristi produkcijski URL webhoka umjesto testnog URL-a. 401 ili 403 upućuje na provjeru autentičnosti ili valjanost potpisa; vremenska ograničenja upućuju na latenciju ili dostupnost odredišta; TLS pogreške upućuju na lanac certifikata, naziv hosta ili istek.

Povezano#