Webhook e consegna

Dopo ogni chiamata Hanc.AI può inviare la chiamata — riepilogo, trascrizione, campi estratti — al Suo sistema: un sistema di ticket, un CRM, un ERP o qualsiasi endpoint HTTPS. Questa pagina descrive esattamente come si comporta questa consegna: che cosa accade quando il Suo server non è raggiungibile, quante volte riproviamo, che cosa deve consentire il Suo firewall e come si presenta la richiesta.

Tutti i piani

La consegna post-chiamata con nuovi tentativi e registro delle consegne è disponibile su tutti i piani, incluso Free.

Che cosa viene inviato, e quando

Una richiesta parte non appena la chiamata è terminata e la sua analisi è conclusa (riepilogo, sentiment, i Suoi campi estratti) — in genere pochi secondi dopo il riaggancio.

Origine	Dove si configura
Azione Chiamata API	Agente → Azioni → Post call → Chiamata API
Passaggio di workflow	Workflow Builder → passaggio di tipo strumento Chiamata API con Quando viene eseguito: Dopo la chiamata
Webhook dell'agente	Il campo `webhook_url` dell'agente (riferimento API)

Le richieste che un agente effettua durante una conversazione (strumenti Live Call) non rientrano in questa pagina: servono in quel preciso istante e non vengono mai ripetute in seguito.

Quando il Suo server non è disponibile

Nulla va perso. La richiesta viene salvata in una coda di consegna prima del primo tentativo e vi rimane finché il Suo server non la accetta o la pianificazione non si esaurisce.

Una consegna è considerata riuscita quando il Suo endpoint risponde con un qualsiasi stato 2xx entro 30 secondi.
In tutti gli altri casi si riprova: connessione rifiutata, errori DNS o TLS, timeout e qualsiasi altro stato — 5xx, 429 e anche 4xx. Se una chiave API è scaduta e Lei la rinnova, le chiamate in attesa arrivano da sole.
Ogni tentativo invia la stessa richiesta con lo stesso ID di consegna.

Pianificazione dei nuovi tentativi

Tentativo	Pausa che lo precede	Tempo trascorso dalla fine della chiamata
1	— (subito)	~0
2	1 minuto	~1 min
3	5 minuti	~6 min
4	30 minuti	~36 min
5	2 ore	~2 h 36 min
6	6 ore	~8 h 36 min
7	24 ore	~1 giorno 8 h
8	48 ore	~3 giorni 8 h

In totale 8 tentativi in circa 3,4 giorni — abbastanza per coprire un'interruzione durante il fine settimana.

La Sua pianificazione

In un'azione Chiamata API (e in un passaggio di workflow Chiamata API eseguito dopo la chiamata) può sostituire la pianificazione in Nuovi tentativi in caso di errore:

fino a 10 nuovi tentativi,
ogni pausa da 1 minuto a 7 giorni,
rimuova tutte le righe per inviare una sola volta, senza nuovi tentativi.

Un'azione che non ha mai modificato segue la pianificazione predefinita riportata sopra.

Dopo l'ultimo tentativo

La consegna viene contrassegnata come Non consegnato, Lei riceve una notifica via email, a meno che non l'abbia disattivata, e la richiesta viene conservata per 30 giorni. In questo periodo può inviarla di nuovo — con un clic nel registro delle consegne o con una chiamata API. Il nuovo invio è possibile anche per una consegna già riuscita, ad esempio dopo un ripristino dal Suo lato.

Indipendentemente da qualsiasi webhook, la chiamata stessa resta nel Suo account Hanc.AI — trascrizione, riepilogo, registrazione e campi estratti sono disponibili in Log chiamate e tramite l'API. Un'interruzione prolungata ritarda il passaggio dei dati al Suo sistema; non cancella la conversazione.

Almeno una volta

La consegna avviene almeno una volta. In rari casi — ad esempio quando il Suo server ha elaborato una richiesta ma la risposta non ci è arrivata in tempo — la stessa chiamata arriva due volte. Usi X-Hanc-Delivery-Id per riconoscere una ripetizione e ignorarla.

Notifiche in caso di errore

Non è necessario tenere d'occhio il registro: un'azione può avvisare via email quando la sua richiesta non viene consegnata. Scelga in Notifica in caso di errore nell'azione (o nel passaggio di workflow):

Impostazione	Quando viene inviata l'email
Dopo l'ultimo tentativo (predefinita)	Una volta, quando la pianificazione dei nuovi tentativi è esaurita e la richiesta è contrassegnata come Non consegnato
Dopo ogni tentativo fallito	Dopo ogni tentativo fallito, con l'orario del successivo — e dopo l'ultimo
Non notificare	Mai; gli errori sono visibili solo nel registro

L'email indica l'azione e l'agente, l'host del Suo server, che cosa ha risposto (ad esempio HTTP 503 o timeout after 30s), di quale tentativo si trattava e su quanti, e rimanda con un link al registro delle consegne. Quella finale indica inoltre fino a quando la richiesta viene conservata e che può essere inviata di nuovo.

Invia a imposta il destinatario — in genere chi gestisce il sistema ricevente. Se il campo resta vuoto, l'email va al titolare dell'account. È scritta nella lingua dell'account.

Per evitare che un'interruzione inondi la Sua casella di posta, le notifiche sono limitate per azione a 10 all'ora e 30 al giorno; l'ultima prima di una pausa indica fino a quando questa dura. Ogni errore viene comunque annotato nel registro. Per una richiesta che Lei invia di nuovo manualmente non viene inviata alcuna notifica.

Registro delle consegne

Ogni tentativo viene registrato: orario, stato HTTP o errore di rete, durata e inizio della risposta del Suo server.

Nell'app: CRM → Comunicazioni → apra una voce di tipo Chiamata API. Vedrà lo stato (Consegnato, Nuovo tentativo, Non consegnato), tutti i tentativi, l'orario del successivo e il pulsante Invia di nuovo.

Tramite l'API (si autentichi con la Sua chiave API in x-api-key):

Richiesta	Risultato
`GET /v1/webhook-deliveries`	Le Sue consegne, dalla più recente. Filtri: `status` (`pending`, `delivered`, `failed`), `agent_id`, `call_id`, `limit`, `offset`
`GET /v1/webhook-deliveries/{id}`	Una consegna con tutti i tentativi e il corpo della richiesta
`POST /v1/webhook-deliveries/{id}/resend`	La invia di nuovo subito e restituisce l'esito

{
  "id": "6ac71fb82e4f72e709a4a566",
  "delivery_id": "0b0f2f0e-6c0f-4f0b-9c55-3c6a3a1f8a11",
  "kind": "api_call",
  "name": "Create ticket",
  "call_id": "6ac71f9d2e4f72e709a4a4f0",
  "status": "pending",
  "attempts_made": 2,
  "attempts_max": 8,
  "next_attempt_at": "2026-10-09T11:36:04.000Z",
  "attempts": [
    { "n": 1, "at": "2026-10-09T11:30:03.512Z", "duration_ms": 212, "error": "connection refused" },
    { "n": 2, "at": "2026-10-09T11:31:04.007Z", "duration_ms": 187, "status_code": 503, "error": "HTTP 503", "response_preview": "Service Unavailable" }
  ]
}

I valori degli header della richiesta salvata (le Sue chiavi) non vengono mai restituiti.

Rete e firewall

Hanc.AI chiama il Suo endpoint — la connessione viene sempre aperta dal nostro lato verso il Suo.


Direzione	In uscita da Hanc.AI → in entrata dal Suo lato
Indirizzi IP di origine	`178.104.10.47` (servizio di consegna) e `128.140.65.92` (servizio chiamate, usato come riserva)
Protocollo	HTTPS (TLS 1.2 o successivo). L'HTTP non cifrato funziona, ma è sconsigliato
Porta	`443`, oppure la porta indicata nel Suo URL
Versione IP	IPv4
Certificato	Deve essere valido ed emesso da un'autorità di certificazione pubblica; i certificati autofirmati vengono rifiutati
Tempo di risposta	Risponda entro 30 secondi — idealmente confermi subito la ricezione ed elabori in background
Reindirizzamenti	Seguiti, fino a 5

Indirizzi consentiti: se il Suo firewall o il Suo WAF filtra per indirizzo di origine, autorizzi i due indirizzi indicati sopra per il percorso del Suo webhook. Comunichiamo in anticipo un'eventuale modifica di questi indirizzi.

Non possibile: indirizzi all'interno di una rete privata (10.x, 172.16–31.x, 192.168.x, localhost). L'endpoint deve essere raggiungibile da Internet — direttamente o tramite il Suo reverse proxy / API gateway.

Browser: i webhook funzionano da server a server. Non sono coinvolte impostazioni del browser, estensioni o porte aperte sulle postazioni di lavoro dei dipendenti.

Formato della richiesta

POST, PUT e PATCH trasportano un corpo JSON (Content-Type: application/json, UTF-8).

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "start_timestamp": 1730000000000,
  "end_timestamp":   1730000187000,
  "duration": 187000,
  "call_summary": "Customer reports a broken router and asks for a callback…",
  "transcription": [
    { "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
    { "speaker": "user",  "content": "Hi…",    "timestamp": 1730000003000 }
  ],
  "task_achieved": true,
  "sentiment": { "sentiment": "neutral", "explanation": "…" },
  "custom_analysis_data": {
    "customer_number": "K-20417",
    "ticket_category": "Hardware",
    "priority": "high"
  },
  "collected_data": { },
  "transfer_history": [ ],
  "recording_url": "https://…",
  "disconnection_reason": "user_hangup"
}

Campo	Contenuto
`call_summary`	Riepilogo della conversazione
`transcription`	Conversazione completa, turno per turno, con timestamp
`call_from`, `call_to`, `direction`	Chiamante, numero chiamato, in entrata o in uscita
`start_timestamp`, `end_timestamp`, `duration`	Ora Unix e durata in millisecondi
`custom_analysis_data`	I Suoi campi, estratti dalla conversazione — veda Variabili di recupero
`collected_data`	Dati raccolti dall'agente durante la chiamata
`sentiment`, `task_achieved`	Tono della conversazione e se il suo obiettivo è stato raggiunto
`recording_url`	Link alla registrazione, se la registrazione è attiva
`transfer_history`	Trasferimenti avvenuti durante la chiamata

Per GET e DELETE gli stessi campi viaggiano nella query string; i valori annidati come transcription vengono omessi.

Header

Header	Significato
`X-Hanc-Delivery-Id`	Identifica la consegna. Identico a ogni tentativo — lo usi per ignorare i duplicati
`X-Hanc-Attempt`	Numero del tentativo, a partire da `1`
`X-Correlation-Id`	ID di tracciamento interno; lo indichi quando contatta l'assistenza
`User-Agent`	`HANC-Webhooks/1.0`
i Suoi header	Tutto ciò che ha configurato nell'azione

Autenticazione

È Lei a decidere come il Suo endpoint ci riconosce:

Chiave API o token — aggiunga un header all'azione, ad es. Authorization: Bearer <token> o X-API-Key: <key>. Gli header vengono inviati a ogni tentativo.
Basic auth — Authorization: Basic <base64(user:password)>.
Parametro query — per i sistemi che si aspettano la chiave nell'URL.
Indirizzo di origine — consenta solo gli indirizzi IP elencati sopra.

I metodi possono essere combinati; la configurazione abituale è una chiave più un elenco di indirizzi IP consentiti.

Adattare la richiesta al proprio sistema

Per impostazione predefinita la richiesta contiene l'intera chiamata (veda Formato della richiesta). Per un sistema che si aspetta una propria struttura — come la maggior parte dei sistemi di ticket — è Lei a descrivere tale struttura e a compilarla con i dati della chiamata.

Variabili

In un'azione Chiamata API post-chiamata e in un passaggio di workflow Chiamata API, l'URL, gli header, i parametri query e il corpo accettano variabili tra doppie parentesi graffe. Vengono compilate con i dati della chiamata subito prima che la richiesta parta.

Variabile	Valore
`{{call_id}}`	ID della chiamata
`{{call_from}}`, `{{call_to}}`	Chiamante e numero chiamato
`{{customer_phone}}`, `{{customer_email}}`	Numero ed email dell'interlocutore, qualunque sia la direzione della chiamata
`{{call_direction}}`, `{{call_type}}`	`inbound` / `outbound`, `phone` / `web`
`{{call_start}}`, `{{call_end}}`	Inizio e fine, ISO 8601 (UTC)
`{{call_duration}}`	Durata in secondi
`{{call_summary}}`	Riepilogo della conversazione
`{{call_transcription}}`	Conversazione completa come testo
`{{call_sentiment}}`, `{{call_task_achieved}}`	Tono e se l'obiettivo è stato raggiunto
`{{call_recording_url}}`	Link alla registrazione
`{{agent_id}}`	ID dell'agente
i Suoi campi	Ogni Variabile di recupero con il suo nome, ad es. `{{customer_number}}`, `{{priority}}` — e ogni variabile raccolta da un workflow durante la chiamata

Alcune regole utili da conoscere:

Un campo del corpo composto da una sola variabile mantiene il tipo di quella variabile: "priority": "{{priority}}" viene inviato come numero 3, "urgent": "{{urgent}}" come true. Il testo attorno a una variabile la trasforma in testo.
Un valore inserito nell'URL viene codificato automaticamente con la codifica percentuale (+43… diventa %2B43…).
Una variabile per la quale la chiamata non ha alcun valore viene inviata vuota — mai come testo letterale {{name}}.

Nell'app, il pulsante {x} in un campo elenca le variabili disponibili; nel corpo, digitando {{ vengono suggerite.

Corpo

In Corpo (JSON) nell'azione scriva l'oggetto JSON che il Suo sistema si aspetta, annidato quanto necessario:

{
  "ticket": {
    "subject": "Call from {{customer_phone}}: {{ticket_category}}",
    "comment": { "body": "{{call_summary}}" },
    "priority": "{{priority}}",
    "custom_fields": [
      { "id": 360001, "value": "{{customer_number}}" },
      { "id": 360002, "value": "{{call_recording_url}}" }
    ],
    "tags": ["phone-agent"]
  }
}

Solo i Suoi campi

Con Invia solo i miei campi attivato, la richiesta contiene soltanto il Suo corpo e i Suoi parametri query — i dati della chiamata non vengono aggiunti. Se lo lascia disattivato, i Suoi campi vengono inviati insieme alla chiamata completa.

Invio selettivo

Una condizione in linguaggio naturale («solo se il chiamante segnala un guasto») decide quali chiamate attivano la richiesta. Più azioni possono puntare a sistemi o endpoint diversi.

Collegare un sistema di ticket

Qualsiasi sistema di ticket con un'API HTTP o un webhook in ingresso può ricevere le chiamate — direttamente, senza software intermedio. Che cosa serve dal Suo lato:

Un endpoint raggiungibile da Internet tramite HTTPS che accetti JSON.
Una credenziale per accedervi (chiave API, token o basic auth), inserita come header nell'azione.
Se filtra per indirizzo — i due indirizzi IP indicati sopra nel Suo elenco di indirizzi consentiti.

Poi, nell'azione:

Definisca i Suoi campi. Aggiunga Variabili di recupero come numero cliente, categoria del ticket, priorità, richiamata richiesta. L'agente le compila a partire dalla conversazione.
Scriva il corpo secondo la struttura della Sua API di ticket e inserisca le variabili al posto giusto.
Attivi Invia solo i miei campi.
Prema Testa configurazione API, quindi effettui una chiamata di prova.

Saremo lieti di preparare insieme a Lei il corpo per il Suo sistema.

Test

Test di connessione. Il pulsante Testa configurazione API nell'azione invia subito una richiesta di esempio e mostra se il Suo endpoint è stato raggiunto.

Test dei nuovi tentativi — per vedere il meccanismo con i propri occhi:

Nell'azione imposti una pianificazione breve in Nuovi tentativi in caso di errore, ad esempio tre pause da 1 minuto.
Arresti il Suo endpoint o blocchi i nostri indirizzi nel firewall.
Effettui una chiamata di prova all'agente.
Apra CRM → Comunicazioni: la voce mostra Nuovo tentativo, il tentativo fallito con il relativo errore e l'orario del successivo.
Riavvii l'endpoint (o rimuova il blocco). Il tentativo successivo consegna la chiamata e la voce passa a Consegnato — oppure prema Invia di nuovo per consegnare subito.

Checklist per il Suo endpoint

Risponda 2xx non appena la richiesta è stata salvata; svolga in seguito l'elaborazione più onerosa.
Tratti X-Hanc-Delivery-Id come una chiave di idempotenza.
Risponda 4xx/5xx quando non ha potuto accettare la richiesta — riproveremo.
Mantenga valido il certificato e autorizzati i due indirizzi di origine.

Che cosa viene inviato, e quando​

Quando il Suo server non è disponibile​

Pianificazione dei nuovi tentativi​

La Sua pianificazione​

Dopo l'ultimo tentativo​

Notifiche in caso di errore​

Registro delle consegne​

Rete e firewall​

Formato della richiesta​

Header​

Autenticazione​

Adattare la richiesta al proprio sistema​

Variabili​

Corpo​

Solo i Suoi campi​

Invio selettivo​

Collegare un sistema di ticket​

Test​

Checklist per il Suo endpoint​