Webhook
Richiede il feature flag Webhook, attivabile in base al piano del tenant (vedi Feature flag).
I webhook permettono di ricevere notifiche in tempo reale su eventi della piattaforma verso un endpoint esterno gestito dal tenant.
Prerequisiti
- Feature flag Webhook attivo sul tenant.
- Un endpoint HTTPS raggiungibile dall'esterno, pronto a ricevere richieste POST.
- Ruolo di amministratore o Super Admin.
Creare un webhook
- Aprire Amministrazione → Webhook e selezionare Nuovo webhook.
- Indicare nome, URL dell'endpoint e la categoria/evento a cui il webhook si sottoscrive (agente, analisi, sincronizzazione database, documenti, knowledge base o scraping).
- Salvare: il sistema genera automaticamente un secret HMAC-SHA256 dedicato al webhook.
Verificare la firma dei payload
Ogni richiesta inviata dalla piattaforma include l'header X-Askme-Signature, contenente la firma HMAC-SHA256 del corpo della richiesta calcolata con il secret del webhook. Il destinatario deve ricalcolare la firma sullo stesso corpo e confrontarla con quella ricevuta prima di considerare attendibile il payload.
import hashlib
import hmac
def verifica_firma(corpo_richiesta: bytes, secret: str, firma_ricevuta: str) -> bool:
firma_calcolata = hmac.new(
secret.encode("utf-8"), corpo_richiesta, hashlib.sha256
).hexdigest()
return hmac.compare_digest(firma_calcolata, firma_ricevuta)
Un endpoint che non verifica la firma accetta payload da chiunque conosca l'URL. Verificare sempre la firma prima di elaborare il contenuto della richiesta.
Gli eventi disponibili
| Categoria | Eventi |
|---|---|
| Documenti | Caricamento, cancellazione |
| Scraping | Avvio, completamento, fallimento |
| Sincronizzazione database | Completamento, fallimento |
| Knowledge base | Creazione, cancellazione |
| Agente | Creazione, aggiornamento, cancellazione |
| Analisi | Completamento, fallimento |
Testare l'invio
Il pulsante Invia test sulla riga del webhook invia un payload di prova all'endpoint configurato, utile per verificarne la raggiungibilità e la corretta gestione della firma prima di sottoscrivere eventi reali.
Problemi comuni
| Problema | Causa probabile | Soluzione |
|---|---|---|
| L'endpoint non riceve mai le notifiche | URL non raggiungibile dall'esterno o certificato HTTPS non valido | Verificare la raggiungibilità con Invia test e controllare il certificato |
| La verifica della firma fallisce sempre | Il secret usato lato destinatario non corrisponde a quello generato, oppure il corpo viene modificato prima del calcolo dell'HMAC | Ricontrollare il secret copiato e calcolare la firma sul corpo grezzo della richiesta, non su una sua rielaborazione |
| Alcuni eventi non arrivano | Il webhook non è sottoscritto alla categoria dell'evento atteso | Verificare la categoria/evento configurati sul webhook |