Webhookvégpontok

A végpontalapú webhookrendszerrel szervezetenként több célhelyet is regisztrálhat, amelyek mindegyike saját titkos kulccsal, állapottal és az eseménytípusok egy részhalmazára vonatkozó 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, amelyet a visszamenőleges kompatibilitás érdekében tartunk fenn, de szervezetenként csak egy URL-t támogat.

Végpontok

Metódus	Útvonal	Kötelező 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}/test`	`admin+`	Aláírt tesztkézbesítés küldése

Végpontobjektum

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

Mező	Típus	Leírás
`id`	UUID	Végpontazonosító
`label`	string	Megjelenített név, 1–120 karakter
`url`	string	HTTPS URL; fejlesztéshez engedélyezett a `http://localhost`
`events`	array of string	Előfizetett eseménytípusok (lásd az érvényes értékeket). Az üres tömb minden eseményre feliratkozik
`status`	string	`active`, `disabled` (manuálisan szüneteltetve) vagy `failing` (automatikusan beállítva, ha egy kézbesítés egyetlen 2xx nélkül kimeríti a 24 órás újrapróbálkozási ütemezését)
`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 ellenőrzéséhez anélkül, hogy a teljes értéket felfedné
`created_at`, `updated_at`	timestamp

A végpont teljes secret értéke létrehozáskor egyszer jelenik meg, ezt követően soha többé. Tárolja biztonságosan — ha elveszíti, törölje a végpontot, majd hozza létre újra.

Érvényes eseménytípusok

Az events mezőt pontosan ezzel a készlettel validáljuk — a listán kívüli értékek 400 választ adnak vissza. Az egyes típusok payloadstruktúráját lásd az Eseménykatalógusban.

telephony.incoming, telephony.complete, telephony.tool
web.incoming, web.complete, web.tool
call.graded
issue.reported
test-call.completed
alert.triggered

Végpontállapotok

active — a kézbesítések normálisan zajlanak.
disabled — manuálisan szüneteltetve PATCH segítségével. Nem küldünk kéréseket. Soha nem módosítjuk a disabled végpont állapotát; az active állapotra való visszaállítás mindig az Ön döntése.
failing — automatikusan beállítva, ha egy végpontra irányuló kézbesítés a teljes újrapróbálkozási ütemezését (8 kísérlet 24 óra alatt) kimeríti anélkül, hogy valaha is 2xx választ kapna. A hibás végpont nem kap további forgalmat. Miután kijavította a végpontot, PATCH segítségével á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, ott folytatódnak, ahol abbahagyták.

Végpontok listázása

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

Végpontobjektumok tömbjét adja vissza.

Webhook-végpont létrehozása

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

Kérelemmezők

Mező	Típus	Kötelező	Leírás
`label`	string	igen	1–120 karakter
`url`	string	igen	HTTPS URL (`http` csak `localhost` / `127.0.0.1` esetén engedélyezett)
`events`	array	nem	Üresen hagyva vagy elhagyva minden eseményre feliratkozik. A Érvényes eseménytípusok alatt felsorolt értékeket kell használni; az ismétlődések eltávolításra kerülnek

201 Created választ ad vissza a végpontobjektummal, valamint egy további felső szintű secret mezővel, amely a nyers aláírókulcsot tartalmazza — egy 48 karakteres hexadecimális karakterláncot:

{
  "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éket tartalmazzák. A válasz elvetése előtt másolja a teljes értéket a titokkezelőjébe.

Webhook-végpont frissítése

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`	string
`url`	string
`events`	array
`status`	string	`active` vagy `disabled`. Állítsa `active` értékre a szerver által `failing` állapotúnak jelölt végpont újbóli engedélyezéséhez

200 OK választ ad vissza a frissített végpontobjektummal.

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 folyamat használatával, beleértve a kanonikus JSON-szerializálást, az X-ThunderPhone-Signature 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 annak events szűrőjétől függetlenül.

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

A végpont az alábbihoz hasonló burkolót kap:

{
  "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ő kísérlet után 200 OK választ ad vissza, akkor is, ha a célhely hibát küld vissza. A kézbesítés eredményét a success, status, response_code és error mezőkben ellenőrizheti:

{
  "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ő kísérlet sikertelen, a kézbesítés ugyanazt az újrapróbálkozási ütemezést követi, mint a normál eseménykézbesítések.

Végpont törlése

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álkozások megszakadnak.

Kapcsolódó témák

Eseménykatalógus

Az előfizethető events értékek teljes listája.

Webhookok áttekintése

Aláírás-ellenőrzés és kézbesítési szemantika.

Webhooks

Function Tools

Végpontok

Végpontobjektum

Érvényes eseménytípusok

Végpontállapotok

Végpontok listázása

Webhook-végpont létrehozása

Kérelemmezők

Webhook-végpont frissítése

Tesztkézbesítés küldése

Végpont törlése

Kapcsolódó témák

Eseménykatalógus

Webhookok áttekintése

​Végpontok

​Végpontobjektum

​Érvényes eseménytípusok

​Végpontállapotok

​Végpontok listázása

​Webhook-végpont létrehozása

​Kérelemmezők

​Webhook-végpont frissítése

​Tesztkézbesítés küldése

​Végpont törlése

​Kapcsolódó témák

Eseménykatalógus

Webhookok áttekintése

Végpontok

Végpontobjektum

Érvényes eseménytípusok

Végpontállapotok

Végpontok listázása

Webhook-végpont létrehozása

Kérelemmezők

Webhook-végpont frissítése

Tesztkézbesítés küldése

Végpont törlése

Kapcsolódó témák