> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Endpoint webhook
> Gestisci più URL webhook con segreti e filtri degli eventi per 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](/api-reference/organizations#legacy-single-url-webhook),
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
```json theme={null}
{
"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](#valid-event-types)). 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](/it/webhooks/events) 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
```bash cURL theme={null}
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Restituisce un array di [oggetti endpoint](#endpoint-object).
***
## Crea un endpoint
```bash cURL theme={null}
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"]
}'
```
```python Python theme={null}
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](#valid-event-types); i duplicati vengono rimossi |
Restituisce `201 Created` con l'[oggetto Endpoint](#endpoint-object) più
un campo `secret` aggiuntivo di primo livello contenente la chiave di firma non elaborata: una
stringa esadecimale di 48 caratteri:
```json theme={null}
{
"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
```bash cURL theme={null}
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](#endpoint-object) 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`.
```bash cURL theme={null}
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:
```json theme={null}
{
"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:
```json theme={null}
{
"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
```bash cURL theme={null}
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
L'elenco completo dei valori `events` a cui puoi iscriverti.
Verifica della firma e semantica di consegna.