Webhooks

Puncte terminale webhook

Gestionați mai multe URL-uri webhook cu secrete pentru fiecare punct terminal și filtre de evenimente.

Sistemul de webhook-uri bazat pe endpointuri vă permite să înregistrați mai multe destinații per organizație, fiecare cu propriul secret, propriul status și propria abonare la un subset de tipuri de evenimente. Acesta este modelul recomandat pentru toate integrările noi.

Comparați cu webhook-ul vechi cu un singur URL, care este păstrat pentru compatibilitate retroactivă, dar acceptă un singur URL per organizație.

Endpointuri#

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

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 încărcăturii utile a fiecărui tip.

• 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

Statusuri endpoint#

• active — livrările sunt efectuate normal.
• disabled — pus în pauză manual prin PATCH. Nu sunt trimise cereri. Nu modificăm niciodată statusul unui endpoint disabled; readucerea acestuia la active vă aparține întotdeauna.
• failing — setat automat când o livrare către endpoint își epuizează întregul program de reîncercări (8 încercări în 24 de ore) fără să primească vreodată un 2xx. Un endpoint care este în starea de eșec nu mai primește trafic. După remedierea endpointului, faceți PATCH pentru a-i readuce statusul la active; livrările al căror program de reîncercări nu s-a epuizat încă reiau de unde au rămas.

Listează endpointurile#

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

Returnează o matrice 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#

Returnează 201 Created cu obiectul Endpoint, plus un câmp suplimentar secret la nivel 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"
}

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

Returnează 200 OK cu obiectul Endpoint actualizat.

Trimiteți o livrare de test#

Trimiteți un eveniment sintetic webhook.test către un endpoint folosind 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 normale de evenimente.

Ș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 asociate#