Passa al contenuto principale

Webhook e consegna

Dopo ogni chiamata, il riepilogo, la trascrizione e i campi estratti arrivano al tuo sistema — con nuovi tentativi quando non è raggiungibile, un registro delle consegne e un'email quando qualcosa non va.

Tutti i piani, prova inclusaIl tuo endpoint

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, prova gratuita inclusa.

Cosa puoi fare​

  • Inviare ogni chiamata al tuo sistema — un sistema di ticketing, un CRM, un ERP o qualsiasi endpoint HTTPS, quando la chiamata e la sua analisi sono concluse.
  • Dare forma alla richiesta — il tuo body JSON, intestazioni e parametri di query, compilati con variabili della chiamata.
  • Inviare solo alcune chiamate — una condizione in linguaggio naturale decide quali chiamate attivano la richiesta.
  • Non perdere mai una chiamata — le consegne non riuscite vengono ritentate per circa 3,4 giorni, registrate e possono essere reinviate.
  • Venire a sapere degli errori — un'email quando una richiesta non viene consegnata.

Come configurarlo​

  1. Aggiungi una Chiamata API dopo la chiamata

    Apri l'agente → Azioni → Aggiunga strumento → Dopo la chiamata → Chiamata API. In un workflow usa invece un nodo Strumento con Chiamata API e Quando viene eseguito: Dopo la chiamata.

  2. Descrivi la richiesta

    Dagli un nome, una condizione facoltativa, l'URL del tuo endpoint e il metodo HTTP. Aggiungi le intestazioni di cui il tuo endpoint ha bisogno per riconoscerci (vedi Autenticazione) e, se il tuo sistema si aspetta una propria struttura, il Corpo (JSON) con variabili (vedi Dare forma alla richiesta).

    La finestra di creazione dell'azione Chiamata API: nome, condizione, URL dell'endpoint API, metodo HTTP, intestazioni, parametri di query, corpo e Invia solo i miei campi
  3. Imposta i nuovi tentativi e l'email di errore

    Mantieni il programma predefinito o impostane uno tuo in Nuovi tentativi in caso di errore, e scegli chi riceve un'email in Notifica in caso di errore.

    Nuovi tentativi in caso di errore con il programma predefinito, Notifica in caso di errore e Invia a, e il pulsante Testa configurazione API
  4. Provalo

    Premi Testa configurazione API, poi fai una chiamata di prova. Vedi Test.

Scenari di esempio​

Un ticket per ogni segnalazione di guasto Chi chiama segnala un router guasto → l'agente compila i tuoi campi numero cliente, categoria ticket e priorità → dopo la chiamata il tuo sistema di ticketing riceve un ticket nella sua struttura, con Invia solo i miei campi attivo.

Solo le chiamate che contano La condizione «solo se chi chiama segnala un guasto» è soddisfatta → la richiesta va al tuo sistema di assistenza; le altre chiamate non vanno da nessuna parte, oppure a una seconda azione che punta al tuo CRM.

Il tuo server è stato giù nel fine settimana I primi tentativi falliscono → la richiesta viene ritentata secondo il programma → quando il tuo server torna attivo, la chiamata arriva da sola; se il programma si esaurisce, ricevi un'email e puoi reinviarla dal registro delle consegne.

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.

OrigineDove si configura
Azione Chiamata APIAgente → Azioni → Post call → Chiamata API
Passaggio di workflowWorkflow Builder → nodo Strumento (finestra Configuri Strumento) → Chiamata API con Quando viene eseguito: Dopo la chiamata. Veda Workflow → Strumento
Webhook dell'agenteIl 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​

TentativoPausa che lo precedeTempo trascorso dalla fine della chiamata
1— (subito)~0
21 minuto~1 min
35 minuti~6 min
430 minuti~36 min
52 ore~2 h 36 min
66 ore~8 h 36 min
724 ore~1 giorno 8 h
848 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 Strumento con 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):

ImpostazioneQuando 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 fallitoDopo ogni tentativo fallito, con l'orario del successivo — e dopo l'ultimo
Non notificareMai; 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):

RichiestaRisultato
GET /v1/webhook-deliveriesLe 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}/resendLa 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.

DirezioneIn uscita da Hanc.AI → in entrata dal Suo lato
Indirizzi IP di origine178.104.10.47 (servizio di consegna) e 128.140.65.92 (servizio chiamate, usato come riserva)
ProtocolloHTTPS (TLS 1.2 o successivo). L'HTTP non cifrato funziona, ma è sconsigliato
Porta443, oppure la porta indicata nel Suo URL
Versione IPIPv4
CertificatoDeve essere valido ed emesso da un'autorità di certificazione pubblica; i certificati autofirmati vengono rifiutati
Tempo di rispostaRisponda entro 30 secondi — idealmente confermi subito la ricezione ed elabori in background
ReindirizzamentiSeguiti, 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).

{
"id": "6ac7ea6eca60c6024b465c70",
"agent_id": "6ac2a93e36bad261cf088684",
"call_from": "+431234567890",
"call_to": "+439876543210",
"direction": "inbound",
"call_type": "phone",
"call_status": "success",
"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",
"is_anonymous": false,
"is_simulation": false,
"created_at": 1730000000000,
"updated_at": 1730000187000
}
CampoContenuto
id, agent_idLa chiamata e l'agente che l'ha gestita
call_summaryRiepilogo della conversazione
transcriptionConversazione completa, turno per turno, con timestamp
call_from, call_to, directionChiamante, numero chiamato, in entrata o in uscita
call_type, call_statusphone o web; success o failed
start_timestamp, end_timestamp, durationOra Unix e durata in millisecondi
custom_analysis_dataI Suoi campi, estratti dalla conversazione — veda Variabili di recupero
collected_dataDati raccolti dall'agente durante la chiamata
sentiment, task_achievedTono della conversazione e se il suo obiettivo è stato raggiunto
recording_urlLink alla registrazione, se la registrazione è attiva
transfer_historyTrasferimenti avvenuti durante la chiamata
disconnection_reasonCome si è conclusa la chiamata, ad esempio user_hangup, agent_hangup, call_transfer, voicemail
is_anonymous, is_simulationIl chiamante ha nascosto il proprio numero; la chiamata era un test simulato
created_at, updated_atQuando il record della chiamata è stato creato e aggiornato l'ultima volta (ora Unix, ms)

Vengono inviati solo questi campi. Nessun'altra informazione sulla chiamata lascia la piattaforma.

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

Header​

HeaderSignificato
X-Hanc-Delivery-IdIdentifica la consegna. Identico a ogni tentativo — lo usi per ignorare i duplicati
X-Hanc-AttemptNumero del tentativo, a partire da 1
User-AgentHANC-Webhooks/1.0
i Suoi headerTutto 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 i campi della 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 Strumento con 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.

VariabileValore
{{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 campiOgni 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 ai campi della chiamata.

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:

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

Poi, nell'azione:

  1. 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.
  2. Scriva il corpo secondo la struttura della Sua API di ticket e inserisca le variabili al posto giusto.
  3. Attivi Invia solo i miei campi.
  4. 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:

  1. Nell'azione imposti una pianificazione breve in Nuovi tentativi in caso di errore, ad esempio tre pause da 1 minuto.
  2. Arresti il Suo endpoint o blocchi i nostri indirizzi nel firewall.
  3. Effettui una chiamata di prova all'agente.
  4. Apra CRM → Comunicazioni: la voce mostra Nuovo tentativo, il tentativo fallito con il relativo errore e l'orario del successivo.
  5. 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.