Webhooks

Webhooks verbinden Output.Rocks mit externen Plattformen wie Powercloud, n8n, Binect, E-POSTBUSINESS oder kundeneigenen REST-Endpunkten. Sie werden genutzt, um Dokumente oder E-Mails für Folgeaktionen und Callbacks direkt zu übertragen, Statusänderungen zu empfangen oder Prozesse anzustoßen.

Einen Überblick dazu finden Sie auch im Use-Case E-Mail & Anhänge.

Webhook-Liste

Die Tabelle zeigt alle eingerichteten Webhooks inklusive Identifier, Typ und Mandantenkontext. Im Backend lassen sich über 30 vordefinierte Webhook-Typen auswählen, unter anderem SFTP-Uploads, Powercloud-spezifische Schnittstellen oder generische Custom-Endpoints.

ID, Identifier, Gruppen-Identifier, Aktiv ab, Aktiv, Typ

Mandant, Standard für Umgebungs-Mandanten

Erstellt am, Aktualisiert am

Webhook erstellen

Die Schaltfläche Webhook erstellen öffnet geführte Einstiegskarten für die häufigsten Integrationen. SFTP, SharePoint und DropBox führen durch Upload-Ziel, Upload-Format und Details. Binect und E-POSTBUSINESS konfigurieren den physischen Druckversand. Powercloud öffnet einen eigenen Dialog, in dem zuerst der Anwendungsfall, danach bei Bedarf der Subtyp und anschließend Dokument oder E-Mail gewählt wird.

Powercloud-Erstellung

Der Powercloud-Dialog bildet die produktiv nutzbaren Powercloud-Typen ab:

ZUGFeRD-Mapping für Dokumente und E-Mail-Anhänge

Die ZUGFeRD-Mapping-Webhooks für Powercloud (prerender-powercloud-zugferd-mapping-document) und kVASy (prerender-kvasy-zugferd-mapping-document) werden weiterhin als Dokument-Webhooks konfiguriert. Dieselbe Konfiguration greift automatisch auch für PDF-Dokumente, die aus einer Dokumentvorlage als Anhang eines E-Mail-Prozesses gerendert werden.

Der Webhook wird dabei dem Dokumentprozess des Anhangs zugeordnet und vor dessen Rendering ausgeführt. Er läuft nicht auf dem übergeordneten E-Mail-Prozess. Deshalb zeigt die Webhook-Liste für diese Typen in der Spalte Für E-Mails weiterhin Nein an.

Identifier, Gruppen-Identifier und Gruppenbedingungen werden wie bei normalen Dokumentprozessen ausgewertet. Bei einer Gruppenbedingung steht das jeweilige Attachment-Template als Prozesskontext zur Verfügung.

Druckdienstleister-Webhooks

Binect und E-POSTBUSINESS sind Webhook-Typen für physischen Briefversand. Sie erzeugen nach dem Rendering eigene Drucksendungen, die unter Druckversand überwacht werden.

API-Webhook-Typen

Für kundeneigene APIs, Demo-Endpunkte und Automationsplattformen gibt es Webhook-Typen für zwei unterschiedliche Stellen im Rendering-Ablauf: Pre-Rendering und After-Rendering.

Demo API als Pre-Render-Datenquelle

Für die Demo API verwenden Sie bei OAuth2-Webhooks den Client-Credentials-Flow:

Access Token URL: https://demo.example/api/demo/oauth/token
Client ID:        or-demo-enloc
Client Secret:    or-demo-213-enloc
Additional Token Parameters: {}

Eine typische Pre-Rendering-Konfiguration für prerender-custom-oauth2-document oder prerender-custom-oauth2-email ruft den Payload einer hochgeladenen Beispiel-Datei ab:

{
  "method": "GET",
  "url": "https://demo.example/api/demo/files/<file-id>/payload",
  "responseDataRoot": "or",
  "responseDataKey": "example",
  "options": {
    "headers": {
      "Accept": "application/json"
    }
  }
}

Die Antwort steht danach im Rendering unter or.example. Wenn die Antwort direkt in die Rendering-Daten übernommen werden soll, kann responseDataRoot auf renderData gesetzt werden. Mit mergeResponse: true wird eine JSON-Objekt-Antwort in den Zielbereich gemerged; mit responseValuePath kann vorher ein Teil der API-Antwort ausgewählt werden.

Demo API als After-Rendering-Ziel

Für custom-oauth2-document kann ein gerendertes Dokument an die Demo API übergeben werden:

{
  "method": "POST",
  "url": "https://demo.example/api/demo/rendered-documents",
  "responseDataKey": "",
  "options": {
    "headers": {
      "Content-Type": "application/json",
      "Accept": "application/json"
    },
    "json": {
      "fileName": "<<document.filename>>",
      "base64File": "<<document.base64File>>",
      "description": "<<document.description>>",
      "customId": "<<document.customId>>"
    }
  }
}

Für custom-oauth2-email stehen entsprechend <<email.eml.base64File>>, <<email.html.base64File>>, <<email.sender>>, <<email.recipient>>, <<email.subject>> und <<email.attachments>> zur Verfügung. Die Demo API nimmt die Datei entgegen und zeigt sie anschließend in der Demo-Oberfläche bei Rendered Documents an.

Archiv (WORM)

Die Webhook-Typen s3-archive-document und s3-archive-email legen gerenderte Dokumente, E-Mails oder E-Mail-Anhänge im revisionssicheren Archiv ab. Im Konfigurations-Tab werden neben der Aufbewahrungsklasse und dem optionalen Löschzeitpunkt-Offset auch die Archiv-Metadaten gepflegt.

Bei E-Mail-Archiv-Webhooks kann der HTML-Inhalt zusätzlich als PDF archiviert werden. Wird für eine E-Mail-Quelle originalFormat = pdf verwendet, konvertiert Output.Rocks den gerenderten E-Mail-Body nach PDF und speichert ihn mit application/pdf.

Das Feld Archiv-Metadaten akzeptiert ein JSON-Mapping oder einen einzelnen Platzhalter. Nur die dort konfigurierten Werte werden als Metadaten im Archiv gespeichert. Ein leeres Feld oder {} speichert keine Metadaten.

{
  "metadata": {
    "customerId": "<<data.customer.id>>",
    "invoiceNumber": "<<data.invoice.number>>",
    "documentType": "<<metadata.type>>",
    "fileName": "<<document.filename>>"
  }
}

Wenn die Archiv-Metadaten bereits vollständig in den Renderdaten vorbereitet sind, kann das Feld auch nur aus einem Platzhalter bestehen:

{
  "metadata": "<<data.archiveMetadata>>"
}

Der Platzhalter muss auf ein JSON-Objekt auflösen. Listen, einzelne Textwerte oder Zahlen werden nicht als Archiv-Metadaten akzeptiert.

Für E-Mail-Archiv-Webhooks kann das Mapping zusätzlich E-Mail-Kontext verwenden:

{
  "metadata": {
    "customerId": "<<data.customer.id>>",
    "emailSubject": "<<email.subject>>",
    "messageId": "<<email.messageId>>"
  }
}

Verfügbare Platzhalterquellen:

• data: zusammengeführte Renderdaten des Prozesses.
• metadata: Metadaten des aktuellen Dokument- oder E-Mail-Prozesses.
• document: Kontext des gerenderten Dokuments oder E-Mail-Anhangs, z.B. Dateiname, External ID, Custom ID, Rendering-Request-ID und Mandant.
• email: Kontext des E-Mail-Prozesses; bei Anhängen ist das der übergeordnete E-Mail-Prozess.

Archivierte Dokumente können über die M2M-API nach diesen Metadaten gefiltert werden. Der API-Token muss zum Mandanten gehören und das Archiv-Modul muss aktiviert sein:

curl -H "X-AUTH-TOKEN: <api-token>" \
  "https://<backend>/api/archive?metadata[customerId]=C-100&metadata[invoiceNumber]=INV-123"

Die Filterwerte werden exakt verglichen. Mehrere metadata[...]-Parameter werden kombiniert, sodass alle angegebenen Werte passen müssen. Die Datei selbst wird anschließend über den link aus dem Ingest-Response oder per Download-Endpunkt abgerufen:

curl -L -H "X-AUTH-TOKEN: <api-token>" \
  "https://<backend>/api/archive/<id>/download" \
  -o dokument.pdf

Formularstruktur

Details-Tab

Dieser Tab ist bei allen Webhook-Typen identisch und definiert Identifier, Priorität und Aktivierungslogik.

Konfigurations-Tab

Zustellstatus-Trigger für E-Mail-Webhooks

Post-Render-E-Mail-Webhooks können nach dem Zustellstatus gefiltert werden. Im Webhook-Formular wählen Sie dafür Ausführung nach Zustellstatus:

• Immer: Webhook läuft bei zugestellten und gebouncten E-Mails.
• Nur bei Zustellung: Webhook läuft nur, wenn der Mailserver delivered meldet.
• Nur bei Bounce: Webhook läuft nur, wenn der Mailserver bounced meldet.

Die Einstellung ist für generische E-Mail-Uploads, Custom/OAuth2-E-Mail-Webhooks, SFTP, SharePoint, DropBox, Binect, E-POSTBUSINESS, S3-Archiv und die Powercloud-E-Mail-Upload-Typen verfügbar. Pre-Render-Webhooks und Request-Pre-Render-Webhooks bleiben davon ausgenommen.

E-Mail-Upload-Formate

Bei Webhooks mit E-Mail-Upload-Auswahl stehen diese Formate zur Verfügung:

• Vollständige E-Mail (.eml): lädt die komplette E-Mail inklusive MIME-Struktur hoch.
• Nur HTML-Inhalt: lädt den gerenderten E-Mail-Body als .html hoch.
• HTML-Inhalt als PDF: konvertiert den gerenderten E-Mail-Body nach PDF und lädt nur dieses PDF hoch.
• Nur Anhänge: lädt ausschließlich gerenderte und statische E-Mail-Anhänge hoch.
• HTML-Inhalt und Anhänge: lädt den rohen HTML-Body plus Anhänge hoch.
• HTML-Inhalt als PDF und Anhänge: lädt den E-Mail-Body als PDF plus alle Anhänge hoch.

Die PDF-Varianten gelten für SFTP, SharePoint, DropBox, S3-Archiv sowie Powercloud Archive/Custom OAuth2 E-Mail-Uploads. Bestehende Webhooks behalten ihr gespeichertes Format.

Für HTML-Inhalt als PDF und HTML-Inhalt als PDF und Anhänge wird derselbe konfigurierbare E-Mail-PDF-Header wie beim Download im E-Mail-Prozess verwendet. Maßgeblich ist die Einstellung des Mandanten beziehungsweise Umgebungs-Mandanten unter Mandanten-Einstellungen → E-Mail-PDF; dabei gilt die Vererbung Systemstandard → Mandant → Umgebungs-Mandant. Ist der Header dort deaktiviert, bleibt auch das Webhook-PDF ohne Header.

Kontext-Aktionen

Filter

• Filtern öffnet das Modal mit Suchkriterien wie Identifier, Typ oder Mandant.
• Zurücksetzen setzt alle Kriterien zurück und schließt das Modal.
• Anwenden übernimmt die Auswahl, aktualisiert die Tabelle sofort und schließt den Dialog.

Spalten konfigurieren

Das Konfigurationsmodal bietet drei Speicherpfade:

• Für mich anwenden – persönliche Ansicht.
• Als Standard anwenden – gesamte Umgebung nutzt diese Sicht.
• Auf Standard zurücksetzen – ursprüngliche Spaltenauswahl reaktivieren.

Weitere Bedienelemente

• Pagination zeigt im Footer die Anzahl der Treffer (z.B. „2 Ergebnisse“). Bei mehr Seiten erscheinen Zurück/Weiter-Buttons.
• Löschbestätigung: modal-delete fordert eine zusätzliche Bestätigung inklusive Token, bevor ein Webhook endgültig entfernt wird.
• Hidden Delete Form sorgt dafür, dass Löschanfragen signiert und serverseitig geprüft werden.