Endpointuri webhook

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

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 inversă, 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",
  "agent_id": 42,
  "agent_name": "Support Agent",
  "secret_hint": "a1b2…9f0e",
  "paused_at": null,
  "pause_last_error": "",
  "pause_undelivered_count": null,
  "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 payloadului fiecărui tip.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (rezervat; nu este emis încă)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated nu are context de agent și este livrat numai endpointurilor la nivelul întregii organizații.

voice.ready și voice.failed nu pot fi selectate explicit. Pentru a le primi, creați un endpoint la nivelul întregii organizații cu events: []. O listă goală de evenimente primește toate evenimentele acceptate, cu excepția telephony.turn și web.turn, care trebuie selectate explicit.

Stări ale endpointului#

• active — livrările se desfășoară normal.
• disabled — pus manual pe pauză prin PATCH. Nu sunt trimise solicitări. Nu modificăm niciodată starea unui endpoint disabled; revenirea la active depinde întotdeauna de dumneavoastră.
• failing — setat automat atunci 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 răspuns 2xx. Un endpoint în stare de eșec nu mai primește trafic. Trimitem un e-mail proprietarilor și administratorilor organizației dumneavoastră când se întâmplă acest lucru, iar tabloul de bord afișează endpointul pus pe pauză cu un buton Reactivare. După remedierea endpointului, aplicați PATCH pentru a-i schimba starea înapoi la active; livrările al căror program de reîncercări nu s-a epuizat încă reiau de unde au rămas.

Lista endpointurilor#

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

Returnează o matrice de obiecte endpoint. Transmiteți ?agent_id=42 pentru a returna numai endpointurile limitate la acel agent.

Endpointuri limitate la agent#

Endpointurile la nivelul întregii organizații primesc fiecare eveniment corespunzător. Un endpoint cu agent_id primește numai evenimentele corespunzătoare pentru apelurile gestionate de acel agent; evenimentele fără context de agent, precum alert.triggered, nu ajung niciodată la acesta. De asemenea, puteți crea și gestiona aceste endpointuri din secțiunea Webhookuri a constructorului de agenți.

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 de 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.

Rotiți secretul de semnare#

Înlocuiți secretul de semnare al unui endpoint, de exemplu dacă a fost pierdut sau este posibil să fi fost divulgat. Pentru un endpoint asociat unui agent, puteți utiliza și tabloul de bord: deschideți secțiunea Webhook-uri a agentului și selectați Regenerați secretul pentru endpoint. Endpointurile la nivel de organizație sunt rotite prin API.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../rotate-secret \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Returnează 200 OK:

{
  "endpoint": { "id": "c4d5e6f7-...", "secret_hint": "7f3a…c21d", "...": "..." },
  "secret": "7f3a90b2c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5c21d",
  "rotated_endpoint_ids": ["c4d5e6f7-..."]
}

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ă, ambele antete de semnătură, înregistrarea livrării și evidența 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ă, ThunderPhone o reîncearcă o dată, aproximativ un minut mai târziu, apoi se oprește; livrarea afișează atunci status: "failed" în Depanarea livrărilor. O livrare de test nu marchează niciodată endpointul ca failing.

Pentru a configura un declanșator bazat pe structura unui eveniment real, transmiteți un event_type opțional. Livrarea rămâne sintetică și conține "sample": true; mostrele asociate apelurilor folosesc call_id: 0 și agent_id: 0.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event_type":"call.graded"}'

event_type acceptă orice valoare din Tipuri de evenimente valide. Omiterea acestuia păstrează comportamentul generic webhook.test.

Ș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 aflate în curs sunt abandonate.

Depanarea livrărilor#

Înainte de a concluziona că un webhook nu a fost trimis, verificați GET /v1/developer/webhook-deliveries. Aceasta afișează încercările recente din ambele sisteme de webhook, inclusiv ID-ul apelului, originea URL-ului, starea HTTP, numărul de încercări, categoria de eșec permisă și următoarea oră de reîncercare. Nu returnează niciodată sarcina utilă a evenimentului, transcrierea, textul erorii stocate, corpul răspunsului sau calea URL-ului.

Puteți vedea același istoric recent și în Agenți → selectați un agent → Webhook-uri → Livrări recente. Rândurile afișează eticheta endpointului și originea URL-ului utilizată de cea mai recentă încercare. Aceasta este o stare operațională, nu un jurnal de audit imuabil: ștergerea unui endpoint șterge și rândurile sale de livrare.

Pentru un 404 n8n, confirmați mai întâi că fluxul de lucru este activ, acceptă POST și utilizează URL-ul webhook de producție, nu URL-ul de test. Un 401 sau 403 indică autentificarea sau validarea semnăturii; expirările de timp indică latența sau disponibilitatea destinației; erorile TLS indică lanțul de certificate, numele gazdei sau expirarea.

Asociate#