Collega l'agente a servizi esterni con i webhook

Le Azioni Webhook sono una delle skill di IperChat. Quando attivata, puoi definire fino a 10 azioni personalizzate — ognuna è un piccolo “strumento” che l’agente può usare durante la chat per chiamare un endpoint HTTPS esterno.

Ad esempio, puoi creare un’azione check_order_status collegata a un flusso Zapier: quando un utente chiede “dov’è il mio ordine #4521?”, l’agente invoca il webhook con { "order_id": "4521" } e usa la risposta per rispondere all’utente.

Funziona con qualsiasi servizio raggiungibile via HTTPS: Zapier, Make.com, n8n, API REST dei tuoi sistemi, serverless function, ecc.

Attivazione

Dal pannello operativo:

Apri “Il mio Tenant” (menu laterale → gruppo Gestione).
Espandi la sezione “Skills”.
Trova Azioni Webhook e attiva l’interruttore (la skill è contrassegnata come Sperimentale). I permessi correlati — Visualizza webhook e Gestisci webhook (crea, modifica, elimina azioni) — vengono assegnati automaticamente.

Dopo l’attivazione, in sidebar, gruppo Gestione, compare la voce “Webhook”: da qui si creano e gestiscono le azioni.

Creare un’azione webhook

Dalla pagina Webhook clicca ”+ Nuova azione”. Il form raccoglie:

Nome (identificativo)

Il “nome tecnico” dell’azione. Solo lettere minuscole, numeri e underscore, deve iniziare con una lettera (es. check_order_status, create_lead_in_crm). Diventa il nome dello strumento che l’agente vede — quindi sceglilo leggibile.

Descrizione (per l’agent)

Frase in linguaggio naturale che spiega a cosa serve l’azione. L’agente legge questo testo per decidere quando invocarla, quindi scrivila pensando al modello: chiara, specifica, con esempi impliciti di casi d’uso.

Esempio: “Verifica lo stato di spedizione di un ordine a partire dal suo ID.”

URL Webhook

L’endpoint da chiamare. Deve essere HTTPS (HTTP puro è rifiutato), non deve contenere credenziali embedded (user:pass@) e non può puntare a reti private o riservate — c’è una protezione SSRF che blocca anche i tentativi di DNS rebinding al momento dell’esecuzione.

Metodo HTTP e timeout

Metodo: POST (default, payload JSON nel body) oppure GET (parametri convertiti in query string).
Timeout: da 1 a 30 secondi, default 10. Oltre questo tempo l’azione fallisce e l’agente lo comunica all’utente.

Parametri (input per l’agent)

La lista di parametri che l’agente dovrà raccogliere e inviare al webhook. Per ognuno:

Nome — identificativo del campo (lettere minuscole, numeri, underscore).
Tipo — string, number, integer o boolean.
Descrizione — spiega al modello cosa rappresenta il campo e come riempirlo.
Req. — se selezionato, l’agente chiederà esplicitamente il valore all’utente prima di invocare l’azione.

Dietro le quinte, questi parametri diventano uno JSON Schema che viene esposto all’LLM come firma dello strumento.

Headers personalizzati (opzionale)

Coppie chiave/valore da aggiungere alla richiesta HTTP (es. Authorization: Bearer sk-...). Vengono salvate cifrate in Secret Manager e non sono più visibili dopo il salvataggio: se devi cambiarle, le riscrivi.

Abilitata

Interruttore per attivare/disattivare l’azione senza eliminarla. Le azioni disabilitate non compaiono tra gli strumenti dell’agente.

Testare l’azione

Dalla pagina Webhook ogni azione ha un pulsante “Test”: invia al tuo endpoint una richiesta di prova (payload JSON vuoto per POST, nessun parametro per GET) con gli header configurati. In risposta vedi lo status HTTP e i primi 500 caratteri del body.

Utile per verificare che URL, autenticazione e raggiungibilità siano corretti prima di farla usare all’agente.

Come l’agente usa le azioni

Ogni azione abilitata diventa uno strumento disponibile all’LLM in chat. Il comportamento è governato da queste regole:

L’agente decide autonomamente se e quando invocare un’azione, basandosi sulla descrizione e sui parametri.
Aspetta la risposta prima di proseguire nella conversazione.
Non inventa dati: usa solo quanto il webhook restituisce.
Se l’azione fallisce, informa l’utente in modo chiaro e cortese.

Esempio di conversazione

Cliente: Dov’è il mio ordine #4521? Agente: [invoca check_order_status con { "order_id": "4521" }] Agente: Il tuo ordine è attualmente in transito, partito ieri dal magazzino di Milano. La consegna è prevista entro domani mattina.

Formato della risposta

Se il webhook restituisce JSON valido, l’agente lo riceve come oggetto strutturato.
Se restituisce testo non-JSON, l’agente lo riceve come stringa in response_text.
Il body della risposta è limitato a 50 KB: oltre, viene troncato.

Limiti e salvaguardie

Massimo 10 azioni webhook per tenant.
Massimo 10 chiamate webhook per singola conversazione — oltre, l’agente riceve un errore di rate limit.
Timeout massimo 30 secondi per chiamata.
Response cap a 50 KB — in caso di troncamento la risposta è marcata esplicitamente.
Validazione URL ripetuta ad ogni esecuzione (difesa contro DNS rebinding).
Rete privata sempre bloccata — nessun modo di far puntare un webhook a localhost, 10.x.x.x, 192.168.x.x, metadata endpoint cloud, ecc.

Permessi operatore

I due permessi correlati alla skill sono:

Visualizza webhook (webhooks:read) — vede l’elenco delle azioni e le loro configurazioni (eccetto gli header, mai esposti).
Gestisci webhook (webhooks:manage) — crea, modifica, elimina, abilita/disabilita e lancia i test.

Puoi assegnarli a singoli operatori dalla pagina Operatori → Permessi.