---
title: "Webhooki lõpp-punktid"
description: "Halda mitut webhooki URL-i iga lõpp-punkti saladuste ja sündmusefiltritega."
---

Lõpp-punktidel põhinev webhook-süsteem võimaldab registreerida organisatsiooni kohta **mitu**
sihtkohta, millest igaühel on oma saladus, olek ja tellimus teatud sündmusetüüpide
alamhulgale. See on soovitatud mudel kõigi uute integratsioonide jaoks.

Võrdle [pärand ühe URL-iga webhookiga](/api-reference/organizations#legacy-single-url-webhook),
mida säilitatakse tagasiühilduvuse tagamiseks, kuid mis toetab organisatsiooni kohta ainult üht URL-i.

## Lõpp-punktid

| Meetod | Tee | Nõutav roll | Kirjeldus |
|--------|------|---------------|-------------|
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Loetle lõpp-punktid |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Loo lõpp-punkt |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Uuenda silti / URL-i / sündmusi / olekut |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Kustuta lõpp-punkt |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Saada allkirjastatud testiedastus |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Vaata hiljutisi lõpp-punktide ja pärand-edastuste tulemusi |

## Endpointi objekt

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

| Väli | Tüüp | Kirjeldus |
|-------|------|-------------|
| `id` | UUID | Endpointi ID |
| `label` | string | Kuvanimi, 1–120 märki |
| `url` | string | HTTPS-i URL; arenduseks on lubatud `http://localhost` |
| `events` | stringide massiiv | Tellitud sündmuste tüübid (vaata [kehtivaid väärtusi](#valid-event-types)). Tühi massiiv tellib kõik sündmused, välja arvatud ainult selgesõnaliselt valitavad käigupõhised sündmused (`telephony.turn` / `web.turn`) |
| `status` | string | `active`, `disabled` (käsitsi peatatud) või `failing` (määratakse automaatselt, kui edastus läbib 24 h korduskatsete ajakava ilma ühegi 2xx vastuseta) |
| `agent_id` | integer \| null | Agent, millega see endpoint on seotud; `null` tähendab kogu organisatsiooni |
| `agent_name` | string \| null | Seotud agendi nimi või `null` kogu organisatsiooni hõlmava endpointi korral |
| `secret_hint` | string | Allkirjastamise saladuse esimesed 4 ja viimased 4 märki koos ellipsiga (`a1b2…9f0e`) — piisav, et võrrelda seda kohalikult salvestatud saladusega ilma täielikku väärtust avaldamata |
| `created_at`, `updated_at` | timestamp | |

<Note>
  Endpointi täielik `secret` tagastatakse loomisel **ainult ühe korra**
  ja mitte kunagi uuesti. Hoia see turvaliselt alles — kui selle kaotad, kustuta endpoint
  ja loo see uuesti.
</Note>

### Kehtivad sündmuste tüübid

`events` valideeritakse täpselt selle loendi alusel — loendivälised väärtused
tagastavad `400`. Iga tüübi kasuliku koorma vormingu leiad [sündmuste kataloogist](/et/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` ei sisalda agendi konteksti ja edastatakse ainult
kogu organisatsiooni hõlmavatele endpointidele.

`voice.ready` ja `voice.failed` ei ole selgesõnaliselt valitavad. Nende
vastuvõtmiseks loo kogu organisatsiooni hõlmav endpoint väärtusega `events: []`. Tühi sündmuste
loend võtab vastu kõik toetatud sündmused, välja arvatud `telephony.turn` ja `web.turn`,
mis tuleb valida selgesõnaliselt.

### Endpointi olekud

- `active` — edastused toimivad tavapäraselt.
- `disabled` — käsitsi peatatud `PATCH`-iga. Taotlusi ei saadeta. Me ei
  muuda kunagi `disabled` endpointi olekut; selle tagasi
  `active`-ks muutmine on alati sinu otsus.
- `failing` — määratakse automaatselt, kui endpointile suunatud edastus
  kasutab ära kogu korduskatsete ajakava (8 katset 24 tunni jooksul), saamata
  kordagi 2xx vastust. Tõrkuv endpoint ei saa edasist liiklust.
  Kui endpoint on parandatud, muuda selle olek `PATCH`-iga tagasi väärtuseks `active`;
  edastused, mille korduskatsete ajakava pole veel lõppenud, jätkuvad sealt,
  kus need pooleli jäid.

---

## Endpointide loetlemine

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

Tagastab massiivi [endpointi objektidest](#endpoint-object).
Ainult selle agendiga seotud endpointide tagastamiseks edasta `?agent_id=42`.

### Agendiga seotud endpointid

Kogu organisatsiooni hõlmavad endpointid võtavad vastu kõik sobivad sündmused. Endpoint väärtusega
`agent_id` võtab vastu ainult selle agendi hallatud kõnedega seotud sobivad sündmused;
agendi kontekstita sündmused, näiteks `alert.triggered`, ei jõua selleni kunagi. Neid
endpointe saad luua ja hallata ka agendi koostaja jaotises
**Veebikonksud**.

---

## Loo lõpp-punkt

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

### Päringu väljad

| Väli | Tüüp | Kohustuslik | Kirjeldus |
|-------|------|----------|-------------|
| `label` | string | jah | 1–120 märki |
| `url` | string | jah | HTTPS-i URL (`http` on lubatud ainult `localhost`i / `127.0.0.1` puhul) |
| `events` | array | ei | Tühi või välja jäetud väärtus tellib kõik sündmused peale `telephony.turn`i / `web.turn`i, mis nõuavad selgesõnalist tellimust. Kasuta väärtusi, mis on loetletud jaotises [Kehtivad sündmusetüübid](#valid-event-types); duplikaadid eemaldatakse |
| `agent_id` | integer \| null | ei | Piira edastus selle organisatsiooni agendiga; organisatsiooniülese lõpp-punkti jaoks jäta välja või kasuta `null`i |

Tagastab `201 Created` koos [lõpp-punkti objektiga](#endpoint-object) ning
täiendava tipptaseme väljaga `secret`, mis sisaldab toorest allkirjastamisvõtit —
48-märgilist kuueteistkümnendsüsteemi stringi:

```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` tagastatakse **ainult loomisel**. Järgmised `GET`-vastused
  sisaldavad ainult `secret_hint`i. Kopeeri täielik väärtus oma saladuste
  haldurisse enne vastuse sulgemist.
</Warning>

---

## Uuenda lõpp-punkti

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

| Väli | Tüüp | Kirjeldus |
|-------|------|-------------|
| `label` | string | |
| `url` | string | |
| `events` | array | |
| `status` | string | `active` või `disabled`. Määra `active`, et uuesti lubada lõpp-punkt, mille server märkis olekuga `failing` |
| `agent_id` | integer \| null | Määra agendi ID, et piirata lõpp-punkti selle agendiga, või `null`, et muuta see organisatsiooniüleseks |

Tagastab `200 OK` koos uuendatud [lõpp-punkti objektiga](#endpoint-object).

---

## Saada testtarne

Saada sünteetiline `webhook.test` sündmus ühele lõpp-punktile tavapärase
tarnekonveieri kaudu, sealhulgas kanooniline JSON-i serialiseerimine,
`X-ThunderPhone-Signature`, tarne salvestamine ja korduskatsete arvestus.
Test sihib valitud lõpp-punkti sõltumata selle `events` filtrist.

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

Lõpp-punkt saab järgmise ümbriku:

```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 tagastab `200 OK` pärast esimest katset isegi siis, kui sihtkoht
tagastab vea. Tarne tulemi vaatamiseks kontrolli `success`, `status`, `response_code` ja `error` väärtusi:

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

`webhook.test` on sünteetiline ja seda ei saa lisada lõpp-punkti `events`
tellimusse. Kui esimene katse ebaõnnestub, järgib tarne sama
korduskatsete ajakava nagu tavalised sündmuste tarned.

Päästiku seadistamiseks tegeliku sündmuse kuju alusel edasta valikuline
`event_type`. Tarne on endiselt sünteetiline ja sisaldab `"sample": true`;
kõnega seotud näidised kasutavad väärtusi `call_id: 0` ja `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` aktsepteerib mis tahes väärtust loendist [Kehtivad sündmuste tüübid](#valid-event-types).
Selle väljajätmine säilitab üldise `webhook.test` käitumise.

---

## Kustuta lõpp-punkt

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

Tagastab `204 No Content`. URL-ile tarnimine peatub kohe;
pooleliolevatest korduskatsetest loobutakse.

---

## Silu tarneid

Enne kui järeldad, et veebikonksu ei saadetud, kontrolli
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries).
See näitab mõlema veebikonksusüsteemi hiljutisi katseid, sealhulgas kõne ID-d,
URL-i päritolu, HTTP olekut, katsete arvu, lubatud loendisse lisatud tõrkekategooriat ja järgmist
korduskatse aega. See ei tagasta kunagi sündmuse koormust, transkriptsiooni, salvestatud veateksti,
vastuse sisu ega URL-i teed.

Sama hiljutist ajalugu näed ka jaotises **Agendid → vali agent → Veebikonksud →
Hiljutised tarned**. Ridadel kuvatakse lõpp-punkti silt ja uusima
katse kasutatud URL-i päritolu. See on tegevuslik olek, mitte muutumatu auditilogi: lõpp-punkti kustutamine
kustutab ka selle tarneridad.

n8n-i `404` vea korral kontrolli esmalt, et töövoog on aktiivne, aktsepteerib `POST` päringuid ja kasutab
tootmise veebikonksu URL-i, mitte testi-URL-i. `401` või `403` viitab
autentimisele või allkirja valideerimisele; ajalõpud viitavad sihtkoha latentsusele
või saadavusele; TLS-i vead viitavad sertifikaadiahelale, hostinimele või aegumisele.

---

## Seotud

<CardGroup cols={2}>
  <Card title="Sündmuste kataloog" icon="list" href="/et/webhooks/events">
    Täielik loend `events` väärtustest, mida saad tellida.
  </Card>
  <Card title="Veebikonksude ülevaade" icon="bolt" href="/et/webhooks/overview">
    Allkirja valideerimine ja tarne semantika.
  </Card>
</CardGroup>