---
title: "Webhook-végpontok"
description: "Több webhook URL kezelése végpontonkénti titkos kulcsokkal és eseményszűrőkkel."
---
A végpontalapú webhookrendszerrel szervezetenként **több** célhelyet is regisztrálhat, amelyek mindegyike saját titkos kulccsal, saját állapottal és az eseménytípusok egy részhalmazára szóló saját előfizetéssel rendelkezik. Ez az ajánlott modell minden új integrációhoz.
Hasonlítsa össze a [régi, egyetlen URL-es webhookkal](/api-reference/organizations#legacy-single-url-webhook), amelyet a visszamenőleges kompatibilitás érdekében tartunk fenn, de szervezetenként csak egy URL-t támogat.
## Végpontok
| Metódus | Útvonal | Szükséges szerepkör | Leírás |
|--------|------|---------------|-------------|
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Végpontok listázása |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Végpont létrehozása |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Címke / URL / események / állapot frissítése |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Végpont törlése |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/rotate-secret` | `admin+` | Az aláírási titok cseréje |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Aláírt tesztkézbesítés küldése |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | A legutóbbi végpont- és örökölt kézbesítési eredmények megtekintése |
## Végpontobjektum
```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",
"paused_at": null,
"pause_last_error": "",
"pause_undelivered_count": null,
"created_at": "2026-04-20T18:24:10.113Z",
"updated_at": "2026-04-20T18:24:10.113Z"
}
```
| Mező | Típus | Leírás |
|-------|------|-------------|
| `id` | UUID | Végpontazonosító |
| `label` | string | Megjelenítési név, 1–120 karakter |
| `url` | string | HTTPS URL; fejlesztéshez a `http://localhost` engedélyezett |
| `events` | stringek tömbje | Előfizetett eseménytípusok (lásd az [érvényes értékeket](#valid-event-types)). Az üres tömb az összes eseményre előfizet, kivéve a kizárólag kifejezetten megadott, körönkénti eseményeket (`telephony.turn` / `web.turn`) |
| `status` | string | `active`, `disabled` (manuálisan szüneteltetve) vagy `failing` (automatikusan beállítva, ha egy kézbesítés egyetlen 2xx válasz nélkül kimeríti a 24 órás újrapróbálkozási ütemezését) |
| `agent_id` | integer \| null | Az AI-ügynök, amelyhez ez a végpont tartozik; a `null` szervezetszintűt jelent |
| `agent_name` | string \| null | A hozzárendelt AI-ügynök neve, vagy `null` szervezetszintű végpont esetén |
| `secret_hint` | string | Az aláíró titkos kulcs első 4 és utolsó 4 karaktere három ponttal (`a1b2…9f0e`) — elegendő a helyben mentett titkos kulcs azonosításához a teljes érték felfedése nélkül |
| `paused_at` | timestamp \| null | Amikor ThunderPhone a végpontot `failing` állapotba állította. `null`, amíg `active` vagy `disabled` állapotban van |
| `pause_last_error` | string | A végpont szüneteltetésekor bekövetkezett utolsó kézbesítési hiba, például `HTTP 503: Service Unavailable`. Üres, kivéve `failing` állapotban |
| `pause_undelivered_count` | integer \| null | A végpont utolsó sikeres kézbesítése óta nem kézbesített események száma, a szüneteltetéskor számítva |
| `created_at`, `updated_at` | timestamp | |
A végpont teljes `secret` értéke létrehozáskor **egyszer** kerül visszaadásra,
és soha többé. Tárolja biztonságosan — ha elveszíti,
[forgassa el](#rotate-the-signing-secret), hogy újat kapjon.
### Érvényes eseménytípusok
Az `events` mezőt pontosan ezen készlet alapján ellenőrizzük — a listán kívüli
értékek `400` választ adnak vissza. Az egyes típusok hasznos adatainak
szerkezetét az [Eseménykatalógusban](/hu/webhooks/events) találja.
- `telephony.incoming`, `telephony.complete`, `telephony.tool`, `telephony.turn`
- `web.incoming`, `web.complete`, `web.tool`, `web.turn`
- `sms.sent`, `sms.failed`
- `sms.received` (fenntartva; még nincs kibocsátva)
- `call.graded`, `call.data_extracted`, `call.transfer_completed`
- `campaign.completed`
- `issue.reported`, `issue.escalated`
- `test-call.completed`
- `alert.triggered`
Az `issue.escalated` nem rendelkezik AI-ügynök-kontextussal, és csak
szervezetszintű végpontokhoz kerül kézbesítésre.
A `voice.ready` és a `voice.failed` nem választható ki kifejezetten. Ezek
fogadásához hozzon létre egy szervezetszintű végpontot `events: []` értékkel.
Az üres eseménylista minden támogatott eseményt fogad, kivéve a
`telephony.turn` és `web.turn` eseményeket, amelyeket kifejezetten kell
kiválasztani.
### Végpontállapotok
- `active` — a kézbesítések normálisan zajlanak.
- `disabled` — `PATCH` használatával manuálisan szüneteltetve. Nem küldünk kéréseket. Soha nem módosítjuk egy `disabled` végpont állapotát; az `active` állapotba való visszaállítás mindig Önön múlik.
- `failing` — automatikusan beállítjuk, ha egy végpontra történő kézbesítés a teljes újrapróbálkozási ütemezést (8 próbálkozás 24 óra alatt) felhasználja anélkül, hogy valaha 2xx választ kapna. A hibás végpont nem kap további forgalmat. Amikor ez történik, e-mailt küldünk a szervezet tulajdonosainak és rendszergazdáinak, az irányítópult pedig az újraaktiválás gombbal jeleníti meg a szüneteltetett végpontot. Miután a végpont javítva lett, `PATCH` használatával állítsa vissza az állapotát `active` értékre; azok a kézbesítések, amelyeknek az újrapróbálkozási ütemezése még nem járt le, onnan folytatódnak, ahol abbamaradtak.
---
## Végpontok listázása
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
[Végpontobjektumok](#endpoint-object) tömbjét adja vissza.
Adja át a `?agent_id=42` paramétert, hogy csak az adott AI-ügynökhöz tartozó
végpontokat kapja vissza.
### AI-ügynökhöz tartozó végpontok
A szervezetszintű végpontok minden egyező eseményt fogadnak. Az `agent_id`
értékkel rendelkező végpont csak az adott AI-ügynök által kezelt hívásokhoz
tartozó egyező eseményeket fogadja; az AI-ügynök-kontextus nélküli események,
például az `alert.triggered`, soha nem érik el. Ezeket a végpontokat az
AI-ügynökszerkesztő **Webhookok** szakaszában is létrehozhatja és kezelheti.
---
## Végpont létrehozása
```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"]
```
### Kérésmezők
| Mező | Típus | Kötelező | Leírás |
|-------|------|----------|-------------|
| `label` | karakterlánc | igen | 1–120 karakter |
| `url` | karakterlánc | igen | HTTPS URL (`http` csak `localhost` / `127.0.0.1` esetén engedélyezett) |
| `events` | tömb | nem | Üresen hagyva vagy elhagyva minden eseményre feliratkozik, kivéve a `telephony.turn` / `web.turn` eseményeket, amelyekhez explicit feliratkozás szükséges. A [Érvényes eseménytípusok](#valid-event-types) részben felsorolt értékeket kell használni; az ismétlődések eltávolításra kerülnek |
| `agent_id` | egész szám \| null | nem | A kézbesítés hatókörének korlátozása a szervezet egyik ügynökére; szervezetszintű végponthoz hagyja el, vagy használjon `null` értéket |
`201 Created` választ ad vissza a [Végpontobjektummal](#endpoint-object), valamint
egy további felső szintű `secret` mezővel, amely a nyers aláírókulcsot — egy
48 karakteres hexadecimális karakterláncot — tartalmazza:
```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"
}
```
A `secret` **csak létrehozáskor** kerül visszaadásra. A későbbi `GET` válaszok
csak a `secret_hint` értékét tartalmazzák. A válasz bezárása előtt másolja a teljes
értéket a titkoskulcs-kezelőjébe.
---
## Végpont frissítése
```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"]
}'
```
| Mező | Típus | Leírás |
|-------|------|-------------|
| `label` | karakterlánc | |
| `url` | karakterlánc | |
| `events` | tömb | |
| `status` | karakterlánc | `active` vagy `disabled`. Állítsa `active` értékre a szerver által `failing` állapotúnak jelölt végpont újbóli engedélyezéséhez |
| `agent_id` | egész szám \| null | Állítson be ügynökazonosítót a végpont hatókörének korlátozásához, vagy `null` értéket a szervezetszintű használathoz |
`200 OK` választ ad vissza a frissített [Végpontobjektummal](#endpoint-object).
---
## Az aláírási titok cseréje
Cserélje le egy végpont aláírási titkát, például ha elveszett vagy
kiszivároghatott. AI-ügynökhöz tartozó végpont esetén a
vezérlőpultot is használhatja: nyissa meg az ügynök **Webhookok** szakaszát,
és válassza a végpontnál a **Titok újragenerálása** lehetőséget. A szervezetre
kiterjedő végpontok titkát az API-n keresztül cserélheti le.
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
```
| Mező | Típus | Kötelező | Leírás |
|-------|------|----------|-------------|
| `include_copies` | boolean | nem | Alapértelmezett értéke: `true`. Az új titkot a szervezet azon más végpontjaihoz is megadja, amelyeknek az URL-je és jelenlegi titka megegyezik, például ezen végpont más AI-ügynökökön lévő másolataihoz, így egy fogadó továbbra is egyetlen titokkal ellenőrizhet |
`200 OK` választ ad vissza:
```json
{
"endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
"secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
"rotated_endpoint_ids": ["c4d5e6f7-..."]
}
```
| Mező | Típus | Leírás |
|-------|------|-------------|
| `endpoint` | object | Az új `secret_hint` értékkel rendelkező [Endpoint objektum](#endpoint-object) |
| `secret` | string | Az új aláírási titok. Csak ebben a válaszban kerül visszaadásra |
| `rotated_endpoint_ids` | UUID-k tömbje | Minden végpont, amely most az új titkot használja |
A régi titok használata azonnal megszűnik: a következő kézbesítés,
beleértve az újrapróbálkozásokat is, már az új titokkal lesz aláírva. Amíg a fogadója nem rendelkezik
az új titokkal, a kézbesítések nem felelnek meg az aláírás-ellenőrzésen; ha ezekre
nem 2xx állapotkóddal válaszol, a rendszer a szokásos 24 órás
ütemezés szerint újrapróbálja őket, ezért mielőbb frissítse a fogadót. Ha a fogadója
szakaszosan kerül bevezetésre, a bevezetés során mindkét titkot fogadja el — az SDK
ellenőrzési segédfüggvényei titkok listáját fogadják (lásd:
[Webhook-aláírások ellenőrzése](/hu/guides/verify-webhook-signatures)).
---
## Tesztkézbesítés küldése
Küldjön szintetikus `webhook.test` eseményt egy végpontra a normál
kézbesítési folyamaton keresztül, beleértve a kanonikus JSON-szerializálást, mindkét
aláírási fejlécet, a kézbesítés rögzítését és az újrapróbálkozások nyilvántartását.
A teszt a kiválasztott végpontot célozza meg annak `events` szűrőjétől függetlenül.
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
A végpont a következő eseményburkolatot kapja:
```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"
}
```
Az API az első próbálkozás után `200 OK` választ ad vissza, még akkor is, ha a cél
hibát ad vissza. A kézbesítés eredményéhez vizsgálja meg a `success`, `status`, `response_code` és `error`
értékeket:
```json
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}
```
A `webhook.test` szintetikus, és nem adható hozzá egy végpont `events`
feliratkozásához. Ha az első próbálkozás sikertelen, a ThunderPhone körülbelül
egy perccel később egyszer újrapróbálja, majd leáll; a kézbesítés ezután
`status: "failed"` állapotot mutat a [Kézbesítések hibakeresése](#debug-deliveries)
részben. A tesztkézbesítés soha nem jelöli a végpontot `failing` állapotúként.
Valódi eseménystruktúrához való kiváltó konfigurálásához adjon meg egy opcionális
`event_type` értéket. A kézbesítés továbbra is szintetikus marad, és tartalmazza a `"sample": true` értéket;
a híváshoz kapcsolódó minták a `call_id: 0` és `agent_id: 0` értékeket használják.
```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"}'
```
Az `event_type` a [Érvényes eseménytípusok](#valid-event-types) bármely értékét elfogadja.
Az érték elhagyása megőrzi az általános `webhook.test` viselkedést.
---
## Végpont törlése
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
`204 No Content` választ ad vissza. Az URL-re történő kézbesítés azonnal leáll;
a folyamatban lévő újrapróbálások megszakadnak.
---
## Kézbesítések hibakeresése
Mielőtt arra következtetne, hogy egy webhookot nem küldtek el, vizsgálja meg a
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries) végpontot.
Ez mindkét webhookrendszer legutóbbi próbálkozásait mutatja, beleértve a
hívásazonosítót, az URL-eredetet, a HTTP-állapotot, a próbálkozások számát, az
engedélyezési listán szereplő hibakategóriát és a következő újrapróbálás idejét.
Soha nem adja vissza az eseményadatokat, az átiratot, a tárolt hibaszöveget,
a válasz törzsét vagy az URL-útvonalat.
Ugyanezt a közelmúltbeli előzményt a **Ügynökök → Válasszon ki egy ügynököt → Webhookok →
Legutóbbi kézbesítések** menüpontban is megtekintheti. A sorok a végpont címkéjét és a legutóbbi
próbálkozás által használt URL-eredetet mutatják. Ez működési állapot, nem pedig
megváltoztathatatlan auditnapló: egy végpont törlése a hozzá tartozó kézbesítési sorokat is törli.
n8n `404` esetén először ellenőrizze, hogy a munkafolyamat aktív, fogad `POST` kéréseket, és
a teszt URL helyett az éles webhook URL-t használja. A `401` vagy `403`
hitelesítési vagy aláírás-ellenőrzési problémára utal; az időtúllépések a cél késleltetésére
vagy elérhetőségére; a TLS-hibák a tanúsítványláncra, a gépnévre vagy a lejáratra utalnak.
---
## Kapcsolódó
Azon `events` értékek teljes listája, amelyekre feliratkozhat.
Aláírás-ellenőrzés és kézbesítési szemantika.