Webhooks

Webhook-végpontok

Kezeljen több webhook-URL-t végpontonkénti titkos kulcsokkal és eseményszűrőkkel.

A végpontalapú webhookrendszer lehetővé teszi, hogy szervezetenként több célhelyet regisztráljon, amelyek mindegyike saját titkos kulccsal, saját á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 egy URL-es webhookkal, amelyet a visszamenőleges kompatibilitás érdekében tartunk fenn, de szervezetenként csak egy URL-t támogat.

Végpontok#

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

Érvényes eseménytípusok#

Az events mező ellenőrzése pontosan ezzel a készlettel történik — 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, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• call.graded
• issue.reported
• test-call.completed
• alert.triggered

Végpontállapotok#

• active — a kézbesítések normálisan működnek.
• disabled — manuálisan szüneteltetve a PATCH használatával. A rendszer nem küld kéréseket. A disabled végpont állapotát soha nem módosítjuk; az active állapotba való visszaállítás mindig az Ön döntése.
• failing — automatikusan beállítva, amikor a végpontra irányuló kézbesítés kimeríti teljes újrapróbálkozási ütemezését (8 kísérlet 24 óra alatt), és egyszer sem kap 2xx választ. A hibás végpont nem kap további forgalmat. A végpont javítása után PATCH használatával állítsa vissza az állapotát active értékre; azok a kézbesítések, amelyek újrapróbálkozási ütemezése még nem járt le, onnan folytatódnak, ahol abbamaradtak.

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.

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érésmezők#

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

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

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 folyamaton keresztül, 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, még akkor is, ha a célállomás hibát ad vissza. A kézbesítés eredményéhez ellenőrizze a success, status, response_code és error mezőket:

{
  "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ó tartalmak#