AIDA Webhook

Ein Webhook ist ein Ziel, das es AIDA ermöglicht, automatisch einen HTTPS-Endpunkt aufzurufen, sobald ein Dokument von diesem Ziel verarbeitet wird. AIDA führt einen HTTP-POST-Aufruf mit einem JSON-Payload an die konfigurierte URL durch.

Konfiguration

Das Verhalten des Webhooks wird durch die folgenden Parameter in der Ziel-Konfiguration gesteuert:

Parameter	Erforderlich	Beschreibung	Standardwert
Webhook-URL	Ja	Die HTTPS-Endpunkt-URL, die AIDA aufrufen wird.	-
Authorization-Header	Nein	Der Wert für den Authorization HTTP-Header. Zum Beispiel: Bearer Ihr-geheimer-Token.	-
Webhook-Aktion	Nein	Ein Zeichenkettenwert, der dem JSON-Payload im Feld action hinzugefügt wird. Kann verwendet werden, um den Ereignistyp auf der Empfängerseite zu identifizieren.	-
Dokumenten-Versandmodus	Nein	Legt fest, wie die PDF-Datei des Dokuments gesendet wird.	Einen Download-Link in den Payload einbetten
Gültigkeit	Nein	Gültigkeitsdauer des Download-Links für das Dokument.	7 Tage
Dokumenteninhalt hinzufügen	Nein	Wenn aktiviert, wird dem Payload ein content-Feld hinzugefügt, das den vollständigen Text des Dokuments enthält, der per OCR extrahiert wurde.	Deaktiviert
SSL/TLS-Zertifikatsprüfung ignorieren	Nein	Mit Vorsicht verwenden. Wenn aktiviert, validiert AIDA das SSL-Zertifikat des Endpunkts nicht. Nützlich für Tests mit selbstsignierten Zertifikaten.	Deaktiviert

---

HTTP-Header

AIDA sendet die folgenden Header mit der POST-Anfrage:

• Content-Type: application/json
• Accept: application/json
• Authorization: Der Wert, der im Konfigurationsparameter Authorization-Header angegeben wurde, falls vorhanden.

---

JSON-Payload

Der Payload besteht aus einer Reihe von Schlüssel-Wert-Paaren. Einige sind Standardfelder, die von AIDA bereitgestellt werden, während andere den aus dem Dokument extrahierten Eigenschaften entsprechen.

Standardfelder

Diese Felder werden von AIDA automatisch basierend auf der Konfiguration hinzugefügt.

Feld	Typ	Beschreibung
action	string	Der Wert aus der Konfiguration Webhook-Aktion. Nur vorhanden, wenn konfiguriert.
documentURL	string	Ein permanenter Link zur Ansicht des Dokuments in der AIDA-Webanwendung.
downloadURL	string	Ein temporärer, sicherer Link zum Herunterladen der PDF-Datei des Dokuments. Nur vorhanden, wenn der Dokumenten-Versandmodus auf Download (Standard) eingestellt ist.
attachment	string	Der Base64-kodierte Inhalt der PDF-Datei des Dokuments. Nur vorhanden, wenn der Dokumenten-Versandmodus auf Einbetten der Datei eingestellt ist.
content	string	Der vollständige Textinhalt des Dokuments. Nur vorhanden, wenn Dokumenteninhalt hinzufügen aktiviert ist.

Dokumenteneigenschaften

Diese Felder entsprechen den aus dem Dokument extrahierten Daten.

• Schlüssel: Der JSON-Schlüssel für jede Eigenschaft wird durch ihre "Ausgabe-Mapping"-Konfiguration bestimmt. Wenn diese nicht festgelegt ist, wird die Bezeichnung der Eigenschaft verwendet.
• Datentypen: Eigenschaften werden automatisch in den korrekten JSON-Typ umgewandelt (z.B. Number, Boolean, String), basierend auf ihrer Konfiguration in AIDA. Datumsangaben werden als UNIX-Zeitstempel in Millisekunden dargestellt.
• Tabellen: Eigenschaften, die Teil einer Tabelle sind, werden in einem JSON-Array gruppiert. Der Schlüssel für dieses Array wird durch das "Ausgabe-Mapping" der Tabellengruppe oder, falls nicht festgelegt, durch ihren Namen bestimmt.

Beispiel

Gegeben sei ein Dokumententyp mit den folgenden Eigenschaften:

Kopfeigenschaften

• Rechnungsnummer (Bezeichnung: Rechnungsnummer, Ausgabe-Mapping: nicht konfiguriert, Typ: String)
• Rechnungsdatum (Bezeichnung: Rechnungsdatum, Ausgabe-Mapping: invoiceDate, Typ: Date)
• Gesamtbetrag (Bezeichnung: Gesamtbetrag, Ausgabe-Mapping: total, Typ: Currency)

Tabelleneigenschaftsgruppe (Name: Rechnungspositionen, Ausgabe-Mapping: lines):

• Beschreibung (Ausgabe-Mapping: description, Typ: String)
• Menge (Ausgabe-Mapping: qty, Typ: Number)
• Stückpreis (Ausgabe-Mapping: unitPrice, Typ: Currency)

Und die folgende AIDA-Ziel-Konfiguration:

• Webhook-URL: https://api.meinefirma.de/invoice-receiver
• Webhook-Aktion: NEW_INVOICE
• Dokumenten-Versandmodus: download

Der resultierende JSON-Payload, der an den Endpunkt gesendet wird, würde wie folgt aussehen:

{
  "Rechnungsnummer": "INV-2025-042",
  "invoiceDate": 1760444400000,
  "total": 122.00,
  "lines": [
    {
      "description": "Produkt A",
      "qty": 2,
      "unitPrice": 50.00
    },
    {
      "description": "Dienstleistung B",
      "qty": 1,
      "unitPrice": 22.00
    }
  ],
  "action": "NEW_INVOICE",
  "documentURL": "[https://aida.meinefirma.de/app/web/archive/12345](https://aida.meinefirma.de/app/web/archive/12345)",
  "downloadURL": "[https://api.aida.meinefirma.de/asset/document/generated-auth-token](https://api.aida.meinefirma.de/asset/document/generated-auth-token)"
}