> ## 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. # Catalogo eventi > Tutti i tipi di eventi webhook emessi da ThunderPhone. Ogni corpo del webhook ha un campo `type` il cui valore è uno dei tipi di evento in questa pagina. Quando ti iscrivi a un [endpoint](/it/webhooks/endpoints), l'array `events` deve contenere i tipi di evento desiderati (oppure essere vuoto per iscriverti a tutti). Questi eventi vengono inviati in due modalità: * Le **consegne agli endpoint** sono sempre notifiche **non bloccanti** con [ritenti](/it/webhooks/overview): rispondi con qualsiasi 2xx; l'involucro contiene un `event_id` per la deduplicazione. * Gli scambi **bloccanti** vengono eseguiti solo sul [webhook legacy a URL singolo](/it/webhooks/overview): la richiesta di configurazione [`telephony.incoming` / `web.incoming`](/it/webhooks/call-incoming) (numeri in modalità webhook e chiavi widget, timeout di 10 s) e l'invio di [strumenti](/it/tools/overview) in modalità webhook. La tua risposta modella la chiamata in corso. Gli esempi di payload seguenti mostrano l'involucro dell'endpoint nell'ordine di trasmissione (chiavi ordinate alfabeticamente: `data`, `event_id`, `type`); le consegne legacy includono gli stessi `data` senza `event_id`. ## Eventi di chiamata ### `telephony.incoming` Inviato quando una chiamata in entrata raggiunge uno dei tuoi [numeri di telefono](/api-reference/phone-numbers). Le consegne agli endpoint sono notifiche fire-and-forget inviate per **ogni** chiamata in entrata, indipendentemente dal fatto che il numero sia configurato con un agente o con un webhook. I numeri senza un agente assegnato ricevono inoltre la richiesta di configurazione **bloccante** sul webhook legacy — consulta [`telephony.incoming` / `web.incoming`](/it/webhooks/call-incoming) per lo schema completo di richiesta / risposta. ```json theme={null} { "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }, "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11", "type": "telephony.incoming" } ``` ### `telephony.complete` Inviato al termine di una chiamata telefonica in entrata o in uscita. Non bloccante. Include la trascrizione completa, l'URL della registrazione e il riepilogo della fatturazione. Consulta [`telephony.complete` / `web.complete`](/it/webhooks/call-complete) per lo schema del payload. ### `telephony.tool` Inviato dopo che una chiamata telefonica richiama uno [strumento funzione](/it/tools/overview). Notifica di audit non bloccante — lo strumento è già stato eseguito quando questo evento viene consegnato; riguarda i tuoi strumenti funzione (non gli strumenti integrati, della knowledge base, delle connessioni app o MCP). ```json theme={null} { "data": { "arguments": { "date": "2026-04-21" }, "call_id": 987654321, "from_number": "+14155550199", "response": { "response": { "available_slots": ["9:00 AM", "2:00 PM"] }, "status": 200 }, "to_number": "+15551234567", "tool_name": "search_appointments" }, "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2", "type": "telephony.tool" } ``` `response` è il risultato dell'esecuzione: `{"status": , "response": }` in caso di successo oppure `{"status": , "error": ""}` in caso di errore. ### `web.incoming` L'equivalente del canale web di `telephony.incoming`, inviato quando inizia una sessione di [widget web](/it/widget/overview) o una chiamata di test del microfono nel builder. Le consegne agli endpoint sono fire-and-forget per ogni sessione web. Le chiavi pubblicabili in `mode="webhook"` ricevono inoltre la richiesta di configurazione **bloccante** sul webhook legacy — tale richiesta bloccante ha una struttura diversa (`origin_domain`, `publishable_key_prefix`; nessun numero di telefono). Consulta [`telephony.incoming` / `web.incoming`](/it/webhooks/call-incoming). ```json theme={null} { "data": { "call_id": 987654322, "from_number": "web", "origin_domain": "https://example.com", "publishable_key_prefix": "pk_live_a1b2", "to_number": "+15551234567" }, "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d", "type": "web.incoming" } ``` `from_number` è sempre il valore letterale `"web"`. Per le sessioni del widget in modalità webhook, `to_number` è vuoto (il numero dell'agente della sessione viene assegnato dopo la configurazione); per le chiamate di test del microfono nel builder, `origin_domain` e `publishable_key_prefix` sono vuoti. ### `web.complete` L'equivalente del canale web di `telephony.complete`, che copre le chiamate del widget web (`direction: "web"`) e le chiamate di test del microfono nel builder (`direction: "test"`). Non bloccante. Stessa struttura del payload di [`telephony.complete`](/it/webhooks/call-complete), più `origin_domain`, con `from_number` impostato su `"web"`. Sul webhook legacy con URL singolo, le chiamate di test del microfono nel builder vengono storicamente segnalate come `telephony.complete` — solo le chiamate con `direction: "web"` utilizzano qui il tipo `web.complete`. Il sistema degli endpoint mappa sia le chiamate web sia quelle di test su `web.*`. I payload storici possono contenere i valori legacy di `direction` `widget` o `mic`. ### `web.tool` L'equivalente del canale web di `telephony.tool`. `data` contiene `origin_domain` anziché `from_number` / `to_number`. *** ## Eventi di qualità ### `call.graded` Inviato ogni volta che un'[esecuzione di valutazione AI](/api-reference/calls#ai-call-grading) viene completata per una chiamata. Non bloccante. ```json theme={null} { "data": { "call_id": 987654321, "grade": { "call_outcome": "success", "created_at": "2026-04-20T18:25:11.002Z", "detected_issues": [], "graded_at": "2026-04-20T18:25:11.002Z", "grader_model": "heuristic-v1", "id": 5512, "score": 92, "status": "completed", "summary": "Caller asked about their policy and got a full answer…" } }, "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "type": "call.graded" } ``` | Campo | Tipo | Descrizione | | ------------------------------------- | --------------- | ------------------------------------------------------------------------------- | | `grade.id` | integer | ID della valutazione | | `grade.score` | integer \| null | 0–100 | | `grade.call_outcome` | string | `success`, `failure`, `unknown` o `no_conversation` | | `grade.summary` | string | Riepilogo di un paragrafo | | `grade.detected_issues` | array | Stringhe dei problemi rilevati dal valutatore | | `grade.status` | string | Sempre `completed` — vengono emessi solo gli eventi delle esecuzioni completate | | `grade.grader_model` | string | Il valutatore che ha prodotto il risultato (ad es. `heuristic-v1`) | | `grade.graded_at`, `grade.created_at` | timestamp | | Una chiamata può essere valutata più di una volta — una valutazione euristica rapida è spesso seguita da una valutazione completa del modello una volta che la registrazione è disponibile, e sono possibili rivalutazioni manuali. Ogni esecuzione completata emette il proprio evento `call.graded`; considera autorevole il valore `graded_at` più recente. ### `issue.reported` Inviato quando viene creata una [segnalazione di problema](/api-reference/issue-reports) — inviata da un utente dalla dashboard (`source: "user"`) oppure automaticamente dalla valutazione della chiamata (`source: "system"`). Non bloccante. ```json theme={null} { "data": { "call_id": 987654321, "issue_report": { "created_at": "2026-04-20T18:25:11.002Z", "description": "Five-second silence before responding to the main question.", "id": 4321, "severity": "warning", "source": "system", "status": "open", "title": "Agent paused too long" } }, "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "type": "issue.reported" } ``` | Campo | Tipo | Descrizione | | ----------------------- | ------ | ---------------------------------------------------------------------- | | `issue_report.severity` | string | `critical`, `warning` o `info` | | `issue_report.status` | string | `open` o `resolved` | | `issue_report.source` | string | `user` (inviata dalla dashboard) o `system` (creata dalla valutazione) | Rivalutare una chiamata ricrea le relative segnalazioni di problema generate dal sistema, emettendo nuovamente `issue.reported` per le segnalazioni ricreate. Esegui la deduplicazione in base a `call_id` + `title` se vuoi ricevere una sola notifica per ogni problema sottostante. *** ## Eventi delle chiamate di test ### `test-call.completed` Inviato quando un'[esecuzione di chiamata di test](/api-reference/test-calls#test-call-run-object) raggiunge uno stato terminale — `completed` o `failed`, incluse le esecuzioni che non sono riuscite all'avvio e non hanno mai prodotto una chiamata. Non bloccante. Utile per collegare esecuzioni CI batch ai sistemi di chat/notifiche. ```json theme={null} { "data": { "test_call_run": { "call_id": 987654321, "completed_at": "2026-04-20T18:25:04.822Z", "error_message": "", "id": 7110, "status": "completed", "target_id": 12, "target_type": "agent" } }, "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "type": "test-call.completed" } ``` | Campo | Tipo | Descrizione | | ----------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------- | | `test_call_run.target_type` | string | `agent` o `phone_number` | | `test_call_run.target_id` | integer | L'ID dell'agente o del numero di telefono a cui era destinata l'esecuzione, corrispondente a `target_type` | | `test_call_run.status` | string | `completed` o `failed` | | `test_call_run.call_id` | integer \| null | `null` quando l'esecuzione non riesce prima dell'avvio di una chiamata | | `test_call_run.error_message` | string | Vuoto in caso di successo | *** ## Eventi di avviso ### `alert.triggered` Inviato quando una [regola di avviso](/it/guides/alerts) con il canale **Invia ai webhook per sviluppatori** abilitato supera la propria soglia. Non bloccante. Una regola scatta una sola volta e poi rispetta il proprio periodo di cooldown, quindi una violazione persistente produce un evento per ogni finestra di cooldown. ```json theme={null} { "data": { "comparator": "lt", "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d", "fired_at": "2026-04-20T18:00:00+00:00", "metric": "success_rate", "metric_value": 71.4, "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b", "rule_name": "Success rate below 80%", "threshold": 80.0, "window_hours": 24 }, "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a", "type": "alert.triggered" } ``` | Campo | Tipo | Descrizione | | ---------------------- | ------------ | --------------------------------------------------------------------------------------- | | `event_id` (in `data`) | UUID | L'ID di **attivazione** dell'avviso, distinto dall'`event_id` di consegna dell'envelope | | `rule_id`, `rule_name` | UUID, string | La regola che è scattata | | `metric` | string | `success_rate`, `failure_rate`, `avg_score`, `call_volume` o `suite_regression` | | `comparator` | string | `lt`, `lte`, `gt` o `gte` | | `metric_value` | number | Il valore della metrica nella finestra quando la regola è scattata | | `threshold` | number | La soglia configurata | | `window_hours` | integer | Finestra di valutazione retrospettiva | | `fired_at` | timestamp | | Consulta la [guida agli avvisi](/it/guides/alerts) per creare regole, metriche, periodi di cooldown e canali email / Slack. *** ## Correlati Il payload bloccante della chiamata in entrata a cui devi rispondere. Trascrizione e metriche post-chiamata. Sottoscrivi un URL a un sottoinsieme di questi eventi. Come vengono generati gli eventi `telephony.tool` / `web.tool`.