Končne točke spletnih kljuk

Sistem spletnih kavljev, ki temelji na končnih točkah, vam omogoča registracijo več ciljev za posamezno organizacijo, pri čemer ima vsak svoj skrivni ključ, svoje stanje in svojo naročnino na podmnožico vrst dogodkov. To je priporočeni model za vse nove integracije.

Primerjajte s podedovanim spletnim kavljem z enim URL-jem, ki je ohranjen zaradi združljivosti za nazaj, vendar podpira samo en URL na organizacijo.

Končne točke

Objekt končne točke

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

Veljavne vrste dogodkov

events se preveri glede na ta natančen nabor — vrednosti zunaj seznama vrnejo 400. Za obliko koristnega tovora posamezne vrste glejte katalog dogodkov.

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

Stanja končnih točk

• active — dostave potekajo normalno.
• disabled — ročno zaustavljeno prek PATCH. Zahteve se ne pošiljajo. Stanja končne točke disabled nikoli ne spremenimo; odločitev za preklop nazaj v active je vedno vaša.
• failing — nastavljeno samodejno, ko dostava na končno točko izčrpa celoten urnik ponovnih poskusov (8 poskusov v 24 urah), ne da bi kadar koli prejela odgovor 2xx. Neuspešna končna točka ne prejema nadaljnjega prometa. Ko končno točko popravite, s PATCH njeno stanje nastavite nazaj na active; dostave, katerih urnik ponovnih poskusov se še ni iztekel, se nadaljujejo tam, kjer so se ustavile.

Prikažite končne točke

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

Vrne polje objektov končnih točk.

Ustvarite končno točko

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

Polja zahteve

Vrne 201 Created z objektom končne točke in dodatnim poljem secret na najvišji ravni, ki vsebuje surovi podpisni ključ — 48-mestni šestnajstiški niz:

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

Posodobite končno točko

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

Vrne 200 OK s posodobljenim objektom končne točke.

Pošljite testno dostavo

Na eno končno točko pošljite sintetični dogodek webhook.test po običajnem poteku dostave, vključno s kanonično serializacijo JSON, X-ThunderPhone-Signature, beleženjem dostave in upravljanjem ponovnih poskusov. Test cilja izbrano končno točko ne glede na njen filter events.

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

Končna točka prejme ovojnico, kot je ta:

{
  "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 vrne 200 OK po prvem poskusu, tudi če cilj vrne napako. Za rezultat dostave preverite success, status, response_code in error:

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

webhook.test je sintetičen in ga ni mogoče dodati v naročnino events končne točke. Če prvi poskus ne uspe, dostava sledi enakemu urniku ponovnih poskusov kot običajne dostave dogodkov.

Izbrišite končno točko

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

Vrne 204 No Content. Dostava na URL se takoj ustavi; ponovitve, ki so v teku, se opustijo.

Povezano