Endpoint webhook

Gestisci più URL webhook con segreti e filtri degli eventi per ogni endpoint.

Il sistema di webhook basato su endpoint ti consente di registrare più destinazioni per organizzazione, ciascuna con il proprio segreto, il proprio stato e la propria sottoscrizione a un sottoinsieme di tipi di evento. Questo è il modello consigliato per tutte le nuove integrazioni.

Confrontalo con il webhook legacy a URL singolo, mantenuto per la compatibilità con le versioni precedenti ma con supporto per un solo URL per organizzazione.

Endpoint#

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

Tipi di evento validi#

events viene convalidato rispetto a questo set esatto: i valori al di fuori dell'elenco restituiscono 400. Consulta il catalogo degli eventi per la struttura del payload di ogni tipo.

• telephony.incoming, telephony.complete, telephony.tool, telephony.turn
• web.incoming, web.complete, web.tool, web.turn
• sms.sent, sms.failed
• sms.received (riservato; non ancora emesso)
• call.graded, call.data_extracted, call.transfer_completed
• campaign.completed
• issue.reported, issue.escalated
• test-call.completed
• alert.triggered

issue.escalated non ha alcun contesto agente e viene inviato solo agli endpoint a livello di organizzazione.

voice.ready e voice.failed non possono essere selezionati esplicitamente. Per riceverli, crea un endpoint a livello di organizzazione con events: []. Un elenco di eventi vuoto riceve ogni evento supportato tranne telephony.turn e web.turn, che devono essere selezionati esplicitamente.

Stati dell'endpoint#

• active — le consegne avvengono normalmente.
• disabled — messo in pausa manualmente tramite PATCH. Non vengono inviate richieste. Non modifichiamo mai lo stato di un endpoint disabled; decidere di riportarlo a active spetta sempre a te.
• failing — impostato automaticamente quando una consegna all'endpoint esaurisce l'intero programma di nuovi tentativi (8 tentativi in 24 ore) senza mai ricevere un 2xx. Un endpoint in stato di errore non riceve ulteriore traffico. In questo caso inviamo un'email ai proprietari e agli amministratori della tua organizzazione e la dashboard mostra l'endpoint in pausa con un pulsante Riattiva. Una volta corretto l'endpoint, riporta il suo stato a active tramite PATCH; le consegne il cui programma di nuovi tentativi non è ancora terminato riprendono dal punto in cui si erano interrotte.

Elenca endpoint#

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

Restituisce un array di oggetti endpoint. Passa ?agent_id=42 per restituire solo gli endpoint associati a quell'agente.

Endpoint con ambito agente#

Gli endpoint a livello di organizzazione ricevono ogni evento corrispondente. Un endpoint con agent_id riceve solo gli eventi corrispondenti per le chiamate gestite da quell'agente; gli eventi senza contesto agente, come alert.triggered, non lo raggiungono mai. Puoi anche creare e gestire questi endpoint dalla sezione Webhook del builder dell'agente.

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

Campi della richiesta#

Restituisce 201 Created con l'oggetto Endpoint più un campo secret aggiuntivo al livello superiore contenente la chiave di firma non elaborata: una stringa esadecimale di 48 caratteri:

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

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

Restituisce 200 OK con l'oggetto Endpoint aggiornato.

Ruota il segreto di firma#

Sostituisci il segreto di firma di un endpoint, ad esempio quando è stato smarrito o potrebbe essere stato divulgato. Per un endpoint con ambito agente puoi usare anche la dashboard: apri la sezione Webhook dell'agente e seleziona Rigenera segreto sull'endpoint. Gli endpoint a livello di organizzazione vengono ruotati tramite l'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 '{}'

Restituisce 200 OK:

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

Invia una consegna di test#

Invia un evento sintetico webhook.test a un endpoint utilizzando la normale pipeline di consegna, inclusa la serializzazione JSON canonica, entrambe le intestazioni di firma, la registrazione della consegna e la gestione dei tentativi. Il test è indirizzato all'endpoint selezionato indipendentemente dal relativo filtro events.

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

L'endpoint riceve un envelope simile a questo:

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

L'API restituisce 200 OK dopo il primo tentativo, anche se la destinazione restituisce un errore. Esamina success, status, response_code e error per verificare l'esito della consegna:

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

webhook.test è sintetico e non può essere aggiunto all'iscrizione events di un endpoint. Se il primo tentativo non riesce, ThunderPhone lo ritenta una volta circa un minuto dopo e poi si interrompe; la consegna mostra quindi status: "failed" in Debug delle consegne. Una consegna di test non contrassegna mai l'endpoint come failing.

Per configurare un trigger in base alla struttura di un evento reale, passa un event_type facoltativo. La consegna rimane sintetica e contiene "sample": true; gli esempi relativi alle chiamate usano call_id: 0 e 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 accetta qualsiasi valore tra i Tipi di evento validi. Ometterlo mantiene il comportamento generico di webhook.test.

Elimina un endpoint#

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

Restituisce 204 No Content. La consegna all'URL si interrompe immediatamente; i tentativi in corso vengono annullati.

Debug delle consegne#

Prima di concludere che un webhook non sia stato inviato, esamina GET /v1/developer/webhook-deliveries. Mostra i tentativi recenti di entrambi i sistemi webhook, inclusi l'ID della chiamata, l'origine dell'URL, lo stato HTTP, il numero di tentativi, la categoria di errore consentita e l'orario del prossimo tentativo. Non restituisce mai il payload dell'evento, la trascrizione, il testo dell'errore memorizzato, il corpo della risposta o il percorso dell'URL.

Puoi visualizzare la stessa cronologia recente anche in Agenti → seleziona un agente → Webhook → Consegne recenti. Le righe mostrano l'etichetta dell'endpoint e l'origine dell'URL utilizzata dall'ultimo tentativo. Si tratta di uno stato operativo, non di un registro di audit immutabile: l'eliminazione di un endpoint elimina anche le relative righe di consegna.

Per un 404 di n8n, verifica innanzitutto che il workflow sia attivo, accetti POST e utilizzi l'URL webhook di produzione anziché l'URL di test. Un 401 o 403 indica un problema di autenticazione o di convalida della firma; i timeout indicano latenza o disponibilità della destinazione; gli errori TLS indicano la catena di certificati, il nome host o la scadenza.

Correlati#