---
title: "Končne točke webhookov"
description: "Upravljajte več URL-jev webhookov s skrivnostmi in filtri dogodkov za posamezne končne točke."
---

Sistem webhookov, ki temelji na končnih točkah, vam omogoča registracijo **več**
ciljev za posamezno organizacijo, pri čemer ima vsak svojo skrivnost, svoje
stanje in svojo naročnino na podmnožico vrst dogodkov. To je priporočeni model
za vse nove integracije.

Primerjajte s [podedovanim webhookom z enim URL-jem](/api-reference/organizations#legacy-single-url-webhook),
ki je ohranjen zaradi združljivosti za nazaj, vendar podpira le en URL na
organizacijo.

## Končne točke

| Metoda | Pot | Zahtevana vloga | Opis |
|--------|------|---------------|-------------|
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Prikažite seznam končnih točk |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Ustvarite končno točko |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Posodobite oznako / URL / dogodke / stanje |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Izbrišite končno točko |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Pošljite podpisano testno dostavo |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Preglejte nedavne rezultate dostave končnih točk in podedovanih webhookov |

## Predmet končne 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 končne točke |
| `label` | string | Prikazno ime, 1–120 znakov |
| `url` | string | URL HTTPS; `http://localhost` je dovoljen za razvoj |
| `events` | array of string | Vrste naročenih dogodkov (glejte [veljavne vrednosti](#valid-event-types)). Prazno polje naroči na vse dogodke, razen na dogodke za posamezni korak, ki jih je treba izrecno izbrati (`telephony.turn` / `web.turn`) |
| `status` | string | `active`, `disabled` (ročno zaustavljeno) ali `failing` (samodejno nastavljeno, ko dostava izčrpa 24-urni urnik ponovnih poskusov brez enega samega odgovora 2xx) |
| `agent_id` | integer \| null | Agent, na katerega je omejena ta končna točka; `null` pomeni za celotno organizacijo |
| `agent_name` | string \| null | Ime omejenega agenta ali `null` za končno točko za celotno organizacijo |
| `secret_hint` | string | Prvi 4 in zadnji 4 znaki skrivnosti za podpisovanje s tropičjem (`a1b2…9f0e`) — dovolj za preverjanje skrivnosti, ki ste jo shranili lokalno, ne da bi razkrili celotno vrednost |
| `created_at`, `updated_at` | timestamp | |

<Note>
  Celotna vrednost `secret` končne točke je ob ustvarjanju vrnjena **samo enkrat** in
  nikoli več. Varno jo shranite — če jo izgubite, izbrišite končno točko
  in jo znova ustvarite.
</Note>

### Veljavne vrste dogodkov

`events` se preverja glede na ta natančen nabor — vrednosti zunaj seznama
vrnejo `400`. Za obliko koristnega tovora posamezne vrste glejte [Katalog dogodkov](/sl/webhooks/events).

- `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` nima konteksta agenta in se dostavi samo končnim točkam
za celotno organizacijo.

`voice.ready` in `voice.failed` ni mogoče izbrati izrecno. Če ju želite prejemati,
ustvarite končno točko za celotno organizacijo z `events: []`. Prazen seznam dogodkov
prejme vsak podprti dogodek razen `telephony.turn` in `web.turn`,
ki ju morate izbrati izrecno.

### Stanja končne točke

- `active` — dostave potekajo normalno.
- `disabled` — ročno zaustavljeno prek `PATCH`. Zahteve se ne pošiljajo. Stanja
  končne točke `disabled` nikoli ne spreminjamo; ali jo boste znova nastavili na
  `active`, je vedno vaša odločitev.
- `failing` — samodejno nastavljeno, ko dostava na končno točko izčrpa
  celoten urnik ponovnih poskusov (8 poskusov v 24 urah), ne da bi
  kadar koli prejela odgovor 2xx. Končna točka v stanju napake ne prejema nadaljnjega prometa.
  Ko končno točko popravite, z `PATCH` njeno stanje znova nastavite na `active`;
  dostave, katerih urnik ponovnih poskusov še ni potekel, se nadaljujejo tam,
  kjer so se ustavile.

---

## Seznam končnih točk

<CodeGroup>
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Vrne polje [predmetov končne točke](#endpoint-object).
Dodajte `?agent_id=42`, če želite vrniti samo končne točke, omejene na tega agenta.

### Končne točke, omejene na agenta

Končne točke za celotno organizacijo prejemajo vse ujemajoče se dogodke. Končna točka z
`agent_id` prejema samo ujemajoče se dogodke za klice, ki jih obravnava ta agent;
dogodki brez konteksta agenta, kot je `alert.triggered`, je nikoli ne dosežejo. Te
končne točke lahko ustvarite in upravljate tudi v razdelku
**Spletne kljuke** graditelja agenta.

---

## Ustvarite končno točko

<CodeGroup>
```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"]
```
</CodeGroup>

### Polja zahteve

| Polje | Vrsta | Obvezno | Opis |
|-------|------|----------|-------------|
| `label` | niz | da | 1–120 znakov |
| `url` | niz | da | URL HTTPS (`http` je dovoljen samo za `localhost` / `127.0.0.1`) |
| `events` | polje | ne | Prazna ali izpuščena vrednost naroči na vse dogodke, razen `telephony.turn` / `web.turn`, ki zahtevata izrecno naročnino. Uporabiti morate vrednosti, navedene v [Veljavne vrste dogodkov](#valid-event-types); dvojniki se odstranijo |
| `agent_id` | celo število \| null | ne | Omejite dostavo na agenta v tej organizaciji; izpustite ali uporabite `null` za končno točko na ravni organizacije |

Vrne `201 Created` s posodobljenim [objektom končne točke](#endpoint-object) in dodatnim poljem `secret` na najvišji ravni, ki vsebuje neobdelani podpisni ključ — 48-mestni šestnajstiški niz:

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

<Warning>
  `secret` se vrne **samo ob ustvarjanju**. Naslednji odgovori `GET`
  vključujejo samo `secret_hint`. Celotno vrednost kopirajte v upravitelja
  skrivnosti, preden zaprete odgovor.
</Warning>

---

## Posodobite končno točko

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

| Polje | Vrsta | Opis |
|-------|------|-------------|
| `label` | niz | |
| `url` | niz | |
| `events` | polje | |
| `status` | niz | `active` ali `disabled`. Nastavite `active`, da znova omogočite končno točko, ki jo je strežnik označil kot `failing` |
| `agent_id` | celo število \| null | Nastavite ID agenta, da omejite končno točko, ali `null`, da bo veljala za celotno organizacijo |

Vrne `200 OK` s posodobljenim [objektom končne točke](#endpoint-object).

---

## Pošljite preskusno dostavo

Pošljite sintetični dogodek `webhook.test` eni končni točki prek običajnega
poteka dostave, vključno s kanonično serializacijo JSON,
`X-ThunderPhone-Signature`, beleženjem dostave in evidenco ponovnih poskusov.
Preizkus cilja izbrano končno točko ne glede na njen filter `events`.

<CodeGroup>
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Končna točka prejme ovojnico, kot je ta:

```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 po prvem poskusu vrne `200 OK`, tudi če cilj vrne napako.
Za rezultat dostave preverite `success`, `status`, `response_code` in `error`:

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

`webhook.test` je sintetičen in ga ni mogoče dodati v naročnino `events`
končne točke. Če prvi poskus ne uspe, dostava sledi enakemu urniku
ponovnih poskusov kot običajne dostave dogodkov.

Če želite konfigurirati sprožilec za dejansko obliko dogodka, podajte izbirni
`event_type`. Dostava je še vedno sintetična in vsebuje `"sample": true`;
vzorci, povezani s klici, uporabljajo `call_id: 0` in `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` sprejme katero koli vrednost iz razdelka [Veljavne vrste dogodkov](#valid-event-types).
Če ga izpustite, se ohrani splošno vedenje `webhook.test`.

---

## Izbrišite končno točko

<CodeGroup>
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
</CodeGroup>

Vrne `204 No Content`. Dostava na URL se takoj ustavi;
ponovni poskusi v teku se opustijo.

---

## Odpravljanje težav z dostavami

Preden ugotovite, da webhook ni bil poslan, preglejte
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries).
Prikazuje nedavne poskuse iz obeh sistemov webhookov, vključno z ID-jem klica,
izvorom URL-ja, stanjem HTTP, številom poskusov, kategorijo napake s seznama
dovoljenih in časom naslednjega ponovnega poskusa. Nikoli ne vrne podatkovnega
dela dogodka, prepisa, shranjenega besedila napake, telesa odgovora ali poti URL-ja.

Enako nedavno zgodovino lahko vidite tudi v **Agenti → izberite agenta → Webhooki →
Nedavne dostave**. Vrstice prikazujejo oznako končne točke in izvor URL-ja, uporabljen
pri zadnjem poskusu. To je operativno stanje in ne nespremenljiv revizijski dnevnik:
če izbrišete končno točko, se izbrišejo tudi njene vrstice dostav.

Pri napaki n8n `404` najprej potrdite, da je delovni tok aktiven, sprejema `POST` in uporablja
produkcijski URL webhooka namesto preskusnega URL-ja. Napaka `401` ali `403` kaže na
preverjanje pristnosti ali preverjanje podpisa; časovne omejitve kažejo na zakasnitev
ali razpoložljivost cilja; napake TLS kažejo na verigo potrdil, ime gostitelja ali potek veljavnosti.

---

## Povezano

<CardGroup cols={2}>
  <Card title="Katalog dogodkov" icon="list" href="/sl/webhooks/events">
    Celoten seznam vrednosti `events`, na katere se lahko naročite.
  </Card>
  <Card title="Pregled webhookov" icon="bolt" href="/sl/webhooks/overview">
    Preverjanje podpisov in semantika dostave.
  </Card>
</CardGroup>