Endpoint webhook

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

Metodo	Percorso	Ruolo richiesto	Descrizione
`GET`	`/v1/developer/webhook-endpoints`	`admin+`	Elenca gli endpoint
`POST`	`/v1/developer/webhook-endpoints`	`admin+`	Crea un endpoint
`PATCH`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Aggiorna etichetta / URL / eventi / stato
`DELETE`	`/v1/developer/webhook-endpoints/{endpoint_id}`	`admin+`	Elimina un endpoint
`POST`	`/v1/developer/webhook-endpoints/{endpoint_id}/test`	`admin+`	Invia una consegna di test firmata

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

Campo	Tipo	Descrizione
`id`	UUID	ID dell’endpoint
`label`	string	Nome visualizzato, 1–120 caratteri
`url`	string	URL HTTPS; `http://localhost` consentito per lo sviluppo
`events`	array di string	Tipi di evento sottoscritti (vedi i valori validi). Un array vuoto sottoscrive tutti gli eventi
`status`	string	`active`, `disabled` (messo in pausa manualmente) oppure `failing` (impostato automaticamente quando una consegna esaurisce il proprio programma di tentativi di 24 h senza un singolo 2xx)
`secret_hint`	string	Primi 4 e ultimi 4 caratteri del segreto di firma con puntini di sospensione (`a1b2…9f0e`) — sufficienti per confrontarlo con il segreto salvato localmente senza esporre l’intero valore
`created_at`, `updated_at`	timestamp

Il secret completo dell’endpoint viene restituito una sola volta alla creazione e mai più. Conservalo in modo sicuro — se lo perdi, elimina l’endpoint e ricrealo.

Tipi di evento validi

events viene convalidato rispetto a questo insieme esatto — i valori al di fuori dell’elenco restituiscono 400. Consulta il catalogo degli eventi per la struttura del payload di ciascun tipo.

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

Stati dell’endpoint

active — le consegne procedono normalmente.
disabled — messo in pausa manualmente tramite PATCH. Non viene inviata alcuna richiesta. Non modifichiamo mai lo stato di un endpoint disabled; riportarlo a active dipende sempre da te.
failing — impostato automaticamente quando una consegna all’endpoint esaurisce l’intero programma di tentativi (8 tentativi in 24 ore) senza mai ricevere un 2xx. Un endpoint non funzionante non riceve altro traffico. Dopo aver corretto l’endpoint, usa PATCH per riportarne lo stato a active; le consegne il cui programma di tentativi non è ancora esaurito riprendono dal punto in cui si erano interrotte.

Elencare gli endpoint

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

Restituisce un array di oggetti endpoint.

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

Campo	Tipo	Obbligatorio	Descrizione
`label`	string	sì	1–120 caratteri
`url`	string	sì	URL HTTPS (`http` consentito solo per `localhost` / `127.0.0.1`)
`events`	array	no	Se vuoto o omesso, sottoscrive a tutti gli eventi. Deve usare i valori elencati in Tipi di evento validi; i duplicati vengono rimossi

Restituisce 201 Created con l’oggetto Endpoint più un campo secret aggiuntivo di primo livello 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"
}

secret viene restituito solo alla creazione. Le successive risposte GET includono solo secret_hint. Copia il valore completo nel tuo gestore di segreti prima di chiudere la risposta.

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

Campo	Tipo	Descrizione
`label`	string
`url`	string
`events`	array
`status`	string	`active` o `disabled`. Imposta `active` per riattivare un endpoint che il server ha contrassegnato come `failing`

Restituisce 200 OK con l’oggetto Endpoint aggiornato.

Invia una consegna di test

Invia un evento sintetico webhook.test a un endpoint utilizzando la pipeline di consegna standard, inclusi serializzazione JSON canonica, X-ThunderPhone-Signature, registrazione della consegna e gestione dei tentativi. Il test riguarda l’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 come 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. Controlla success, status, response_code e error per 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 alla sottoscrizione events di un endpoint. Se il primo tentativo fallisce, la consegna segue la stessa pianificazione dei tentativi delle normali consegne di eventi.

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

Correlati

Catalogo degli eventi

L’elenco completo dei valori events a cui puoi iscriverti.

Panoramica dei webhook

Verifica della firma e semantica di consegna.

Webhooks

Function Tools

Endpoint

Oggetto endpoint

Tipi di evento validi

Stati dell’endpoint

Elencare gli endpoint

Crea un endpoint

Campi della richiesta

Aggiorna un endpoint

Invia una consegna di test

Elimina un endpoint

Correlati

Catalogo degli eventi

Panoramica dei webhook

​Endpoint

​Oggetto endpoint

​Tipi di evento validi

​Stati dell’endpoint

​Elencare gli endpoint

​Crea un endpoint

​Campi della richiesta

​Aggiorna un endpoint

​Invia una consegna di test

​Elimina un endpoint

​Correlati

Catalogo degli eventi

Panoramica dei webhook

Endpoint

Oggetto endpoint

Tipi di evento validi

Stati dell’endpoint

Elencare gli endpoint

Crea un endpoint

Campi della richiesta

Aggiorna un endpoint

Invia una consegna di test

Elimina un endpoint

Correlati