---
title: "Webhook krajnje točke"
description: "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](/api-reference/organizations#legacy-single-url-webhook),
koji je zadržan radi povratne kompatibilnosti, ali podržava samo jedan URL po
organizaciji.
## Krajnje točke
| Metoda | Putanja | Potrebna uloga | Opis |
|--------|------|---------------|-------------|
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Prikažite popis krajnjih točaka |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Izradite krajnju točku |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Ažurirajte oznaku / URL / događaje / status |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Izbrišite krajnju točku |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Pošaljite potpisanu probnu isporuku |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Pregledajte nedavne rezultate isporuke krajnjih točaka i zastarjelih webhookova |
## Objekt krajnje točke
```json
{
"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"
}
```
| Polje | Vrsta | Opis |
|-------|------|-------------|
| `id` | UUID | ID krajnje točke |
| `label` | string | Naziv za prikaz, 1–120 znakova |
| `url` | string | HTTPS URL; `http://localhost` dopušten je za razvoj |
| `events` | niz stringova | Pretplaćene vrste događaja (pogledajte [važeće vrijednosti](#valid-event-types)). Prazan niz pretplaćuje se na sve događaje osim eksplicitnih događaja po potezu (`telephony.turn` / `web.turn`) |
| `status` | string | `active`, `disabled` (ručno pauzirano) ili `failing` (automatski postavljeno kada isporuka iscrpi raspored ponovnih pokušaja od 24 h bez ijednog 2xx odgovora) |
| `agent_id` | integer \| null | Agent na kojeg je ova krajnja točka ograničena; `null` znači za cijelu organizaciju |
| `agent_name` | string \| null | Naziv ograničenog agenta ili `null` za krajnju točku za cijelu organizaciju |
| `secret_hint` | string | Prva 4 i posljednja 4 znaka tajne za potpisivanje s trotočkom (`a1b2…9f0e`) — dovoljno za usporedbu s tajnom koju ste lokalno spremili, bez otkrivanja pune vrijednosti |
| `created_at`, `updated_at` | vremenska oznaka | |
Puna vrijednost `secret` krajnje točke vraća se **samo jednom** pri izradi i
više nikada. Sigurno je pohranite — ako je izgubite, izbrišite krajnju točku
i izradite je ponovno.
### Važeće vrste događaja
`events` se provjerava prema ovom točnom skupu — vrijednosti izvan popisa
vraćaju `400`. Pogledajte [Katalog događaja](/hr/webhooks/events) 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
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Vraća niz [objekata krajnjih točaka](#endpoint-object).
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
```bash cURL
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"]
}'
```
```python Python
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
| Polje | Vrsta | Obavezno | Opis |
|-------|------|----------|-------------|
| `label` | string | da | 1–120 znakova |
| `url` | string | da | HTTPS URL (`http` je dopušten samo za `localhost` / `127.0.0.1`) |
| `events` | array | ne | Prazno/izostavljeno pretplaćuje na sve događaje osim `telephony.turn` / `web.turn`, koji zahtijevaju izričitu pretplatu. Moraju se upotrijebiti vrijednosti navedene u odjeljku [Valjane vrste događaja](#valid-event-types); duplikati se uklanjaju |
| `agent_id` | integer \| null | ne | Ograničite isporuku na glasovnog agenta u ovoj organizaciji; izostavite ili upotrijebite `null` za krajnju točku na razini cijele organizacije |
Vraća `201 Created` s ažuriranim [objektom krajnje točke](#endpoint-object) i dodatnim poljem `secret` na najvišoj razini koje sadržava neobrađeni ključ za potpisivanje — heksadecimalni niz od 48 znakova:
```json
{
"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"
}
```
`secret` se vraća **samo pri izradi**. Naknadni odgovori `GET` uključuju samo `secret_hint`. Kopirajte punu vrijednost u upravitelj tajni prije nego što odbacite odgovor.
---
## Ažuriranje krajnje točke
```bash cURL
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"]
}'
```
| Polje | Vrsta | Opis |
|-------|------|-------------|
| `label` | string | |
| `url` | string | |
| `events` | array | |
| `status` | string | `active` ili `disabled`. Postavite `active` kako biste ponovno omogućili krajnju točku koju je poslužitelj označio kao `failing` |
| `agent_id` | integer \| null | Postavite ID glasovnog agenta da ograničite krajnju točku ili `null` da bude na razini cijele organizacije |
Vraća `200 OK` s ažuriranim [objektom krajnje točke](#endpoint-object).
---
## 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`.
```bash cURL
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:
```json
{
"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:
```json
{
"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`.
```bash
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](#valid-event-types).
Izostavljanje zadržava općenito ponašanje `webhook.test`.
---
## Izbrišite krajnju točku
```bash cURL
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`](/api-reference/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
Potpuni popis vrijednosti `events` na koje se možete pretplatiti.
Provjera potpisa i semantika isporuke.