Webhook AIDA

Il Webhook è una Destinazione che permette ad AIDA di chiamare automaticamente un endpoint HTTPs ogni volta che un documento viene elaborato da questo flusso. AIDA eseguirà una chiamata HTTP POST con un payload JSON all'URL configurato.

Configurazione

Il comportamento del webhook è controllato dai seguenti parametri nella configurazione della destinazione:

Parametro	Obbligatorio	Descrizione	Valore predefinito
URL del Webhook	Sì	L'URL dell'endpoint HTTPS che AIDA chiamerà.	-
Header di autorizzazione	No	Il valore per l'header HTTP Authorization. Ad esempio: Bearer il-tuo-token-segreto.	-
Azione del Webhook	No	Un valore stringa che sarà aggiunto al payload JSON nel campo action. Può essere usato per identificare il tipo di evento dal lato ricevente.	-
Modalità di invio del documento	No	Definisce come viene inviato il file PDF del documento.	Incorpora un URL di download nel payload
Scadenza	No	Scadenza del link per il download del documento.	7 giorni
Aggiungi contenuto del documento	No	Se abilitato, aggiunge un campo content al payload contenente il testo completo del documento, estratto dall'OCR.	Disabilitato
Ignora la verifica del certificato SSL/TLS	No	Usare con cautela. Se abilitato, AIDA non validerà il certificato SSL dell'endpoint. Utile per test con certificati auto-firmati.	Disabilitato

---

Header HTTP

AIDA invierà i seguenti header con la richiesta POST:

• Content-Type: application/json
• Accept: application/json
• Authorization: Il valore fornito nel parametro di configurazione Header di autorizzazione, se presente.

---

Payload JSON

Il payload è composto da una serie di coppie chiave-valore. Alcuni sono campi standard forniti da AIDA, mentre altri corrispondono alle proprietà estratte dal documento.

Campi Standard

Questi campi sono aggiunti automaticamente da AIDA in base alla configurazione.

Campo	Tipo	Descrizione
action	string	Il valore dalla configurazione Azione del Webhook. Presente solo se configurato.
documentURL	string	Un link permanente per visualizzare il documento all'interno dell'applicazione web di AIDA.
downloadURL	string	Un link temporaneo e sicuro per scaricare il file PDF del documento. Presente solo se la Modalità di invio del documento è impostata su download (predefinito).
attachment	string	Il contenuto codificato in Base64 del file PDF del documento. Presente solo se la Modalità di invio del documento è impostata per incorporare il file.
content	string	Il testo completo del documento. Presente solo se Aggiungi contenuto del documento è abilitato.

Proprietà del Documento

Questi campi corrispondono ai dati estratti dal documento.

• Chiave: La chiave JSON per ogni proprietà è determinata dalla sua configurazione di "Mapping di output". Se non è impostata, viene utilizzata l'Etichetta della proprietà.
• Tipi di Dati: Le proprietà vengono convertite automaticamente nel tipo JSON corretto (es. Numero, Booleano, Stringa) in base alla loro configurazione in AIDA. Le date sono rappresentate come timestamp UNIX in millisecondi.
• Tabelle: Le proprietà che fanno parte di una tabella saranno raggruppate in un array JSON. La chiave per questo array è determinata dal "Mapping di output" del gruppo della tabella o, se non impostato, dal suo Nome.

Esempio

Dato un tipo di documento con le seguenti proprietà:

Proprietà di Intestazione

• Numero fattura (Etichetta: Numero fattura, Mapping di output: non configurato, Tipo: Stringa)
• Data fattura (Etichetta: Data fattura, Mapping di output: invoiceDate, Tipo: Data)
• Importo totale (Etichetta: Importo totale, Mapping di output: total, Tipo: Valuta)

Gruppo di Proprietà Tabella (Nome: Linee Fattura, Mapping di output: lines):

• Descrizione (Mapping di output: description, Tipo: Stringa)
• Quantità (Mapping di output: qty, Tipo: Numero)
• Prezzo unitario (Mapping di output: unitPrice, Tipo: Valuta)

E la seguente configurazione della destinazione AIDA:

• URL del Webhook: https://api.miacompagnia.com/ricevi-fattura
• Azione del Webhook: NUOVA_FATTURA
• Modalità di invio del documento: download

Il payload JSON risultante inviato all'endpoint apparirebbe così:

{
  "Numero fattura": "INV-2025-042",
  "invoiceDate": 1760444400000,
  "total": 122.00,
  "lines": [
    {
      "description": "Prodotto A",
      "qty": 2,
      "unitPrice": 50.00
    },
    {
      "description": "Servizio B",
      "qty": 1,
      "unitPrice": 22.00
    }
  ],
  "action": "NUOVA_FATTURA",
  "documentURL": "[https://aida.miacompagnia.com/app/web/archive/12345](https://aida.miacompagnia.com/app/web/archive/12345)",
  "downloadURL": "[https://api.aida.miacompagnia.com/asset/document/generated-auth-token](https://api.aida.miacompagnia.com/asset/document/generated-auth-token)"
}