Webhook
Richiede la capacità Webhook, attivabile per l'organizzazione (vedi Capacità).
I webhook permettono di ricevere notifiche in tempo reale sugli eventi della piattaforma presso un endpoint esterno gestito dall'organizzazione. Si gestiscono da Impostazioni > API > Webhook.
Prerequisiti
- Capacità Webhook attiva per l'organizzazione.
- Un endpoint HTTPS raggiungibile dall'esterno, pronto a ricevere richieste POST.
- Ruolo con il permesso di gestione delle integrazioni, come l'amministratore. La voce non è visibile all'operatore.
La pagina Webhook
L'intestazione della pagina riporta il numero di webhook attivi e il pulsante Nuovo webhook. Ogni webhook è presentato in una scheda con il nome, l'URL dell'endpoint, lo stato Attivo o Inattivo, gli eventi sottoscritti, indicati come Tutti gli eventi, con il nome dell'unico evento o con il loro numero, e, se presente, la data dell'ultimo invio con il relativo esito. L'interruttore sulla scheda attiva o disattiva il webhook senza aprirlo; il menu della scheda offre Invia test, Modifica ed Elimina, e selezionando la scheda si apre il modulo di modifica.
Creare un webhook
- Aprire Impostazioni > API > Webhook e selezionare Nuovo webhook.
- Indicare il Nome e l'URL endpoint.
- Nel campo Secret (HMAC-SHA256) inserire il segreto con cui firmare i payload, oppure generarne uno casuale con l'icona Genera secret. Copiare il secret e conservarlo nel sistema destinatario prima di salvare: dopo il salvataggio la console non lo mostra più.
- In Eventi sottoscritti selezionare gli eventi da ricevere, raggruppati per categoria; Seleziona tutti e Deseleziona tutti agiscono sull'intero elenco. È necessario selezionare almeno un evento.
- Selezionare Salva.
In modifica, lasciando invariato il campo del secret resta valido il segreto già salvato; inserendo un valore diverso, il nuovo secret sostituisce il precedente e va aggiornato anche nel sistema destinatario.
Verificare la firma dei payload
Ogni richiesta inviata dalla piattaforma include l'header X-Askme-Signature nella forma sha256=<firma>, dove la firma è l'HMAC-SHA256 del corpo della richiesta, in formato esadecimale, calcolato con il secret del webhook. Il destinatario deve ricalcolare la firma sul corpo grezzo ricevuto, prima di qualsiasi decodifica, e confrontarla con il valore dell'header, prefisso compreso, prima di considerare attendibile il payload.
import hashlib
import hmac
def verifica_firma(corpo_richiesta: bytes, secret: str, header_firma: str) -> bool:
firma_calcolata = "sha256=" + hmac.new(
secret.encode("utf-8"), corpo_richiesta, hashlib.sha256
).hexdigest()
return hmac.compare_digest(firma_calcolata, header_firma)
Un endpoint che non verifica la firma accetta payload da chiunque conosca l'URL. Impostare sempre un secret e verificare la firma prima di elaborare il contenuto della richiesta.
Gli eventi disponibili
| Categoria | Eventi |
|---|---|
| Eventi agente | Agente creato, Agente modificato, Agente eliminato |
| Eventi analisi | Analisi completata, Analisi fallita |
| Eventi sincronizzazione DB | Sincronizzazione DB completata, Sincronizzazione DB fallita |
| Eventi documenti | Documento caricato, Documento eliminato |
| Eventi knowledge base | Knowledge Base creata, Knowledge Base eliminata |
| Eventi scraping | Scraping avviato, Scraping completato, Scraping fallito |
Testare l'invio
La voce Invia test nel menu della scheda invia un payload di prova all'endpoint configurato; la console conferma l'invio oppure ne segnala il fallimento. È utile per verificare la raggiungibilità dell'endpoint e la corretta gestione della firma prima di affidarsi agli eventi reali. Dopo un invio, la scheda riporta la data dell'ultimo invio e il suo esito.
Consegne e nuovi tentativi
Se l'endpoint non risponde o restituisce un errore del server (codice 5xx), la piattaforma ritenta l'invio fino a tre volte in totale, a pochi secondi di distanza. Una risposta con codice 4xx è considerata un rifiuto definitivo e non viene ritentata. L'endpoint deve rispondere entro 10 secondi.
Ogni consegna viene registrata con l'evento, l'esito, il numero di tentativi, il codice di risposta e la durata. La scheda del webhook mostra l'esito dell'ultima consegna; il registro completo delle consegne è consultabile tramite le API (vedere API di Askme AI).
Problemi comuni
| Problema | Causa probabile | Soluzione |
|---|---|---|
| L'endpoint non riceve mai le notifiche | Webhook inattivo, URL non raggiungibile dall'esterno o certificato HTTPS non valido | Verificare l'interruttore sulla scheda, provare con Invia test e controllare il certificato |
| La verifica della firma fallisce sempre | La firma calcolata viene confrontata senza il prefisso sha256=, il secret usato dal destinatario non corrisponde a quello salvato, oppure il corpo viene modificato prima del calcolo dell'HMAC | Confrontare il valore completo dell'header con sha256= seguito dalla firma calcolata; se necessario impostare un nuovo secret, aggiornarlo nel destinatario e calcolare la firma sul corpo grezzo della richiesta |
| Alcuni eventi non arrivano | Il webhook non è sottoscritto all'evento atteso, oppure l'endpoint ha risposto con un errore | Aprire il webhook e verificare gli Eventi sottoscritti; controllare l'esito dell'ultimo invio sulla scheda |
| La voce Webhook non compare in Impostazioni | Capacità Webhook non attiva, oppure ruolo senza il permesso di gestione delle integrazioni | Verificare la capacità e il ruolo; per attivare la capacità rivolgersi al team Askme |