Webhooks

Koncové body webhooků

Spravujte více adres URL webhooků s tajnými klíči pro jednotlivé koncové body a filtry událostí.

Systém webhooků založený na koncových bodech vám umožňuje registrovat více cílů pro každou organizaci, každý s vlastním tajným klíčem, vlastním stavem a vlastním odběrem podmnožiny typů událostí. Toto je doporučený model pro všechny nové integrace.

Porovnejte se starším webhookem s jednou adresou URL, který je zachován kvůli zpětné kompatibilitě, ale podporuje pouze jednu adresu URL na organizaci.

Koncové body#

Objekt koncového bodu#

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

Platné typy událostí#

events se ověřuje vůči této přesné sadě — hodnoty mimo seznam vrátí 400. Tvar datové části jednotlivých typů naleznete v katalogu událostí.

• 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

Stavy koncového bodu#

• active — doručování probíhá normálně.
• disabled — ručně pozastaveno pomocí PATCH. Neodesílají se žádné požadavky. Stav koncového bodu disabled nikdy neměníme; rozhodnutí o jeho přepnutí zpět na active je vždy na vás.
• failing — nastaví se automaticky, když doručení do koncového bodu vyčerpá celý plán opakování (8 pokusů během 24 hodin), aniž by kdy získalo odpověď 2xx. Koncový bod ve stavu selhání nepřijímá další provoz. Jakmile koncový bod opravíte, nastavte pomocí PATCH jeho stav zpět na active; doručování, jehož plán opakování ještě neskončil, pokračuje tam, kde skončilo.

Výpis koncových bodů#

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

Vrátí pole objektů koncových bodů.

Vytvoření koncového bodu#

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

Pole požadavku#

Vrátí 201 Created s objektem koncového bodu a dalším polem nejvyšší úrovně secret, které obsahuje nezpracovaný podpisový klíč — 48znakový hexadecimální řetězec:

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

Aktualizace koncového bodu#

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

Vrátí 200 OK s aktualizovaným objektem koncového bodu.

Odeslání testovacího doručení#

Odešlete syntetickou událost webhook.test do jednoho endpointu pomocí běžného procesu doručení, včetně kanonické serializace JSON, X-ThunderPhone-Signature, záznamu doručení a evidence opakovaných pokusů. Test cílí na vybraný endpoint bez ohledu na jeho filtr events.

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

Endpoint obdrží obálku ve tvaru:

{
  "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 vrátí 200 OK po prvním pokusu, i když cílový endpoint vrátí chybu. Výsledek doručení zkontrolujte v polích success, status, response_code a error:

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

webhook.test je syntetická událost a nelze ji přidat do odběru events endpointu. Pokud první pokus selže, doručení se řídí stejným harmonogramem opakovaných pokusů jako běžná doručení událostí.

Odstranění endpointu#

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

Vrátí 204 No Content. Doručování na adresu URL se okamžitě zastaví; probíhající opakované pokusy budou zrušeny.

Související#