Endpointuri webhook

Sistemul de webhookuri bazat pe endpointuri vă permite să înregistrați mai multe destinații pentru fiecare organizație, fiecare cu propriul secret, propriul status și propriul abonament la un subset de tipuri de evenimente. Acesta este modelul recomandat pentru toate integrările noi. Comparați cu webhookul cu un singur URL moștenit, care este păstrat pentru compatibilitate retroactivă, dar acceptă un singur URL per organizație.

Endpointuri

Metodă	Cale	Rol necesar	Descriere
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	Listați endpointurile
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Creați un endpoint
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Actualizați eticheta / URL-ul / evenimentele / statusul
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Ștergeți un endpoint
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	Trimiteți o livrare de test semnată

Obiect endpoint

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

Câmp	Tip	Descriere
`id`	UUID	ID-ul endpointului
`label`	string	Nume afișat, 1–120 de caractere
`url`	string	URL HTTPS; `http://localhost` este permis pentru dezvoltare
`events`	array of string	Tipuri de evenimente abonate (consultați valorile valide). Un array gol se abonează la toate evenimentele
`status`	string	`active`, `disabled` (pus manual pe pauză) sau `failing` (setat automat când o livrare își epuizează programul de reîncercări de 24 h fără niciun 2xx)
`secret_hint`	string	Primele 4 și ultimele 4 caractere ale secretului de semnare, cu puncte de suspensie (`a1b2…9f0e`) — suficiente pentru a verifica secretul salvat local fără a expune valoarea completă
`created_at`, `updated_at`	timestamp

secret-ul complet al endpointului este returnat o singură dată la creare și niciodată după aceea. Stocați-l în siguranță — dacă îl pierdeți, ștergeți endpointul și creați-l din nou.

Tipuri de evenimente valide

events este validat în raport cu acest set exact — valorile din afara listei returnează 400. Consultați Catalogul de evenimente pentru structura payloadului fiecărui tip.

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

Statusuri ale endpointurilor

active — livrările circulă normal.
disabled — pus manual pe pauză prin PATCH. Nu sunt trimise cereri. Nu schimbăm niciodată statusul unui endpoint disabled; revenirea la active depinde întotdeauna de dumneavoastră.
failing — setat automat atunci când o livrare către endpoint își parcurge întregul program de reîncercări (8 încercări în 24 de ore) fără să primească vreodată un 2xx. Un endpoint în stare de eșec nu mai primește trafic. După ce remediați endpointul, actualizați-i statusul înapoi la active prin PATCH; livrările al căror program de reîncercări nu s-a încheiat încă reiau de unde au rămas.

Listați endpointurile

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

Returnează un array de obiecte endpoint.

Creați un endpoint

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

Câmpuri de solicitare

Câmp	Tip	Obligatoriu	Descriere
`label`	șir	da	1–120 de caractere
`url`	șir	da	URL HTTPS (`http` permis numai pentru `localhost` / `127.0.0.1`)
`events`	matrice	nu	Gol/omis se abonează la toate evenimentele. Trebuie să utilizați valorile enumerate în Tipuri de evenimente valide; duplicatele sunt eliminate

Returnează 201 Created cu obiectul endpoint, plus un câmp suplimentar secret la nivelul superior, care conține cheia brută de semnare — un șir hexazecimal de 48 de caractere:

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

secret este returnat numai la creare. Răspunsurile GET ulterioare includ numai secret_hint. Copiați valoarea completă în managerul dumneavoastră de secrete înainte de a închide răspunsul.

Actualizați un endpoint

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

Câmp	Tip	Descriere
`label`	șir
`url`	șir
`events`	matrice
`status`	șir	`active` sau `disabled`. Setați `active` pentru a reactiva un endpoint pe care serverul l-a marcat ca `failing`

Returnează 200 OK cu obiectul endpoint actualizat.

Trimiteți o livrare de test

Trimiteți un eveniment sintetic webhook.test către un endpoint utilizând fluxul normal de livrare, inclusiv serializarea JSON canonică, X-ThunderPhone-Signature, înregistrarea livrării și gestionarea reîncercărilor. Testul vizează endpointul selectat, indiferent de filtrul său events.

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

Endpointul primește un plic precum:

{
  "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-ul returnează 200 OK după prima încercare, chiar dacă destinația returnează o eroare. Verificați success, status, response_code și error pentru rezultatul livrării:

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

webhook.test este sintetic și nu poate fi adăugat la abonamentul events al unui endpoint. Dacă prima încercare eșuează, livrarea urmează același program de reîncercări ca livrările de evenimente normale.

Ștergeți un endpoint

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

Returnează 204 No Content. Livrarea către URL se oprește imediat; reîncercările în curs sunt abandonate.

Resurse conexe

Catalog de evenimente

Lista completă a valorilor events la care vă puteți abona.

Prezentare generală a webhookurilor

Verificarea semnăturii și semantica livrării.

Webhooks

Function Tools

Endpointuri

Obiect endpoint

Tipuri de evenimente valide

Statusuri ale endpointurilor

Listați endpointurile

Creați un endpoint

Câmpuri de solicitare

Actualizați un endpoint

Trimiteți o livrare de test

Ștergeți un endpoint

Resurse conexe

Catalog de evenimente

Prezentare generală a webhookurilor

​Endpointuri

​Obiect endpoint

​Tipuri de evenimente valide

​Statusuri ale endpointurilor

​Listați endpointurile

​Creați un endpoint

​Câmpuri de solicitare

​Actualizați un endpoint

​Trimiteți o livrare de test

​Ștergeți un endpoint

​Resurse conexe

Catalog de evenimente

Prezentare generală a webhookurilor

Endpointuri

Obiect endpoint

Tipuri de evenimente valide

Statusuri ale endpointurilor

Listați endpointurile

Creați un endpoint

Câmpuri de solicitare

Actualizați un endpoint

Trimiteți o livrare de test

Ștergeți un endpoint

Resurse conexe