Inhalt
Dieser Abschnitt beschreibt die vier von der MOXIS REST API unterstützten Integrationsmuster. Jedes Muster deckt einen anderen operativen Kontext ab; vom schnellen Prototyping bis zu produktionsreifen, ereignisgesteuerten Architekturen. Wählen Sie das Integrationsmuster, das zu Ihrer Infrastruktur und Ihren Volumenanforderungen passt.
1. Vergleich der Integrationsmuster
|
Muster |
MOXIS Version |
Echtzeit? |
Komplexität |
Geeignet für |
|
Simple |
Beliebig |
Nein |
Niedrig |
Prototyping, manuelle Workflows |
|
Webhook |
Enterprise Cloud |
Ja |
Mittel |
Produktive, ereignisgesteuerte Integrationen |
|
Polling |
Beliebig |
Nahezu Echtzeit |
Mittel |
Produktion ohne Webhooks |
|
Middleware |
Beliebig |
Abhängig |
Hoch |
Gemeinsam genutzte Infrastruktur für mehrere Anwendungen |
MOXIS Tipp
Enterprise Cloud beinhaltet Webhook-Unterstützung. Business Cloud beinhaltet keine Webhooks, verwenden Sie für diese MOXIS Version das Polling-Muster.
1.1. Auswahl eines Musters
1.1.1. Erstellen eines einfachen Auftrags
Verwenden Sie dieses Integrationsmuster, wenn Sie gerade erst beginnen, einen Proof of Concept erstellen oder Workflows mit geringem Volumen betreiben, bei denen bereits ein Mensch in den Prozess eingebunden ist. Sie benötigen dafür auf Ihrer Seite keine Event-Infrastruktur. Der Nachteil ist, dass Ihre Anwendung den Abschluss aktiv abfragen muss, statt benachrichtigt zu werden. Zudem sind Sie auf die Interaktion der Benutzer mit der MOXIS-Benutzeroberfläche angewiesen.
Siehe Erstellen eines einfachen Auftrags.
1.1.2.Webhook-Integration
Verwenden Sie dieses Integrationsmuster für produktive Integrationen auf Enterprise Cloud, bei denen MOXIS Events aktiv an Ihr System senden soll, sobald sie auftreten. Ihre Anwendung registriert einen HTTPS-Endpunkt, und MOXIS liefert einen Payload, sobald ein Job einen Trigger-Status erreicht. Dies macht Polling vollständig überflüssig und minimiert die Latenz zwischen Signaturabschluss und nachgelagerter Verarbeitung.
Siehe Webhook-Integration.
1.1.3. Polling-Integrationsmuster
Verwenden Sie dieses Integrationsmuster, wenn Webhooks nicht verfügbar sind (zum Beispiel in der MOXIS Business Cloud) oder wenn Ihr Endpunkt von MOXIS aus nicht erreichbar ist (z. B. hinter einer Firewall oder in einer Entwicklungsumgebung). Ein zeitgesteuerter Job fragt MOXIS in regelmäßigen Abständen nach abgeschlossenen Aufträgen ab. Bei sorgfältiger Nutzung des Filters jobFinishedAfter sowie der Paginierung skaliert dieses Muster gut und vermeidet eine erneute Verarbeitung bereits behandelter Jobs.
Siehe Polling-Integration.
1.1.4. Middleware-Integrationsmuster
Verwenden Sie dieses Integrationsmuster, wenn mehrere interne Anwendungen mit MOXIS interagieren müssen und Sie eine einzige, zentral verwaltete Integrationsschicht wünschen. Die Middleware verwaltet die Zugangsdaten, übernimmt Wiederholungsversuche, übersetzt Events aus Webhooks oder Polling und stellt den aufrufenden Anwendungen eine vereinfachte interne API bereit. Dies ist die Option mit der höchsten Komplexität, aber die am besten wartbare bei größerem Maßstab.
Siehe Middleware-Integration.
1.2. Weiterführende Referenzen
-
API-Referenz: Vollständige Methodendokumentation
-
Schnellstartanleitung: Anleitung für den ersten API-Aufruf
-
Authentifizierung: Zugangsdaten und OAuth-Einrichtung
-
Datenmodell der Job-Beschreibung: JSON-Referenz für jobDescription
2. Erstellen eines einfachen Auftrags
Der einfachste Weg, die MOXIS API zu nutzen, besteht darin, ein Dokument hochzuladen, einen Job zu starten und später das signierte Ergebnis abzurufen. Auf Ihrer Seite ist keine Event-Infrastruktur erforderlich. Die Erkennung des Abschlusses erfolgt durch Abfragen des Status eines einzelnen Jobs (Polling) oder durch Abwarten einer Bestätigung des Benutzers außerhalb der API.
2.1. Wann dieses Integrationsmuster verwendet werden sollte
-
Prototyping oder erste Evaluierung der API
-
Workflows mit geringem Volumen, bei denen bereits ein Mensch am Prozess beteiligt ist
-
Szenarien, in denen sich der Benutzer in der MOXIS-Benutzeroberfläche anmeldet, um Dokumente manuell zu signieren und abzurufen
-
Umgebungen, in denen die Einrichtung eines Webhook-Endpunkts oder eines Schedulers noch nicht möglich ist
Das Integrationsmuster ist nicht geeignet für:
-
automatisierte Pipelines,
-
Verarbeitung mit hohem Volumen oder Fälle, in denen eine zeitnahe Benachrichtigung über den Abschluss erforderlich ist.
2.2. Funktionsweise
-
Ihre Anwendung ruft POST startProcess auf, um einen Signaturjob in MOXIS zu erstellen.
-
MOXIS sendet eine E-Mail-Benachrichtigung an den/die konfigurierten Signierenden.
-
Der Signierende öffnet MOXIS, prüft das Dokument und bringt seine Signatur an.
-
Ihre Anwendung ruft regelmäßig GET getJobState auf, um zu prüfen, ob der Job abgeschlossen ist.
-
Sobald der Status FINISHED_SUCCESS lautet, ruft Ihre Anwendung GET getDocument auf, um das signierte PDF abzurufen.
2.3. Sequenzdiagramm
sequenceDiagram
participant App as Your App
participant API as MOXIS API
participant UI as MOXIS UI
participant Signer as Signer
App->>API: POST /startProcess/{processId}
API-->>App: 201 Created — processInstanceId
API->>Signer: Email notification
Signer->>UI: Opens MOXIS, reviews document
Signer->>UI: Applies signature
loop Until FINISHED_SUCCESS
App->>API: GET /getJobState/{processInstanceId}
API-->>App: JSON — state, endDate
end
App->>API: GET /getDocument/{processInstanceId}
API-->>App: Signed PDF (blob)
2.4. Schritt-für-Schritt-Anleitung
2.4.1. Schritt 1: Job erstellen
Senden Sie eine multipart/form-data-POST-Anfrage mit Ihrem PDF und einem jobDescription-JSON-Body.
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/{processId}
Authorization: Basic <base64(user:password)>
Content-Type: multipart/form-data
jobDescription (JSON-Teil):
{
"constituent": {
"classifier": "EMAIL",
"name": "owner@example.com",
"@class": "com.xitrust.moxispe.api.User"
},
"metaData": {
"description": "Contract review Q2 2026",
"referenceId": "CONTRACT-00123"
},
"positionType": "INVISIBLE",
"iterationData": [
{
"invitees": [
{
"@class": "com.xitrust.moxispe.api.User",
"classifier": "EMAIL",
"name": "signer@example.com",
"roleName": "moxisSigner"
}
],
"category": "APPROVAL",
"iterationNumber": 0
}
]
}
Antwort:
HTTP 201 Created
Body: "450123" ← processInstanceId (speichern Sie diesen Wert)
Speichern Sie die processInstanceId. Sie benötigen diese für alle nachfolgenden Aufrufe zu diesem Job.
2.4.2. Schritt 2: Signierender erhält Benachrichtigung und signiert
MOXIS sendet automatisch eine E-Mail an den/die Signierenden. Der Signer meldet sich in der MOXIS-Benutzeroberfläche an, öffnet den Job und schließt die Signatur ab. In dieser Phase ist von Ihrer Anwendung keine Aktion erforderlich.
2.4.3. Schritt 3: Auf Jobabschluss pollen
Rufen Sie GET getJobState mit der processInstanceId auf, um den aktuellen Status zu prüfen.
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobState/{processInstanceId}/{nameClassifier}
Authorization: Basic <base64(user:password)>
Ersetzen Sie {nameClassifier} durch die E-Mail-Adresse oder den UPN des Constituent (Job-Eigentümer).
2.4.4. Beispielantwort (Job noch aktiv):
{
"state": "ACTIVE",
"processInstanceId": 450123,
"endDate": null
}
2.4.5. Beispielantwort (Job abgeschlossen):
{
"state": "FINISHED_SUCCESS",
"processInstanceId": 450123,
"endDate": "2026-04-23T14:30:00Z"
}
Ein Job ist abgeschlossen, wenn beide Bedingungen erfüllt sind: - state ist FINISHED_SUCCESS - endDate ist nicht null
2.4.6. Schritt 4: Signiertes Dokument abrufen
Sobald sich der Job im Status FINISHED_SUCCESS befindet, laden Sie das signierte PDF herunter.
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getDocument/{processInstanceId}
Authorization: Basic <base64(user:password)>
Der Response-Body ist die signierte PDF-Datei (binäres Blob). Speichern Sie diese in Ihrem Speicher.
2.5. Referenz der Job-Status
|
Status |
Beschreibung |
|
DRAFTING |
Job ist ein Entwurf, noch nicht gestartet |
|
ACTIVE |
Job läuft, wartet auf Signatur(en) |
|
POST_PROCESSING |
Signatur abgeschlossen, MOXIS verarbeitet das Ergebnis |
|
FINISHED_SUCCESS |
Erfolgreich signiert — Dokument ist bereit |
|
FINISHED_FAILED |
Signatur fehlgeschlagen |
|
FINISHED_TIMEOUT |
Job vor Abschluss abgelaufen |
|
FINISHED_WF_CANCELLED |
Workflow wurde abgebrochen |
|
FINISHED_SIGNATURE_DENIED |
Ein Signer hat das Dokument abgelehnt |
|
DRAFT_DISMISSED |
Entwurf wurde vor dem Start verworfen |
2.6. Einschränkungen
-
Dieses Muster setzt voraus, dass sich Benutzer aktiv bei MOXIS anmelden, um zu signieren. Es gibt keinen Push-Mechanismus zu Ihrer Anwendung, wenn die Signatur erfolgt.
-
Temporäre Objekte (Entwürfe) unterliegen zeitlichen Beschränkungen. Sie werden nach Ablauf ihres Verfallsdatums automatisch gelöscht.
-
Nicht geeignet für automatisierte, unbeaufsichtigte Pipelines. Ziehen Sie für diese Fälle die Muster Webhook oder Polling in Betracht.
-
Wenn Sie die processInstanceId bei der Erstellung nicht speichern und den Job später finden müssen, verwenden Sie GET lookupJobStates mit den entsprechenden Filtern. Details zu Bulk-Abfragen finden Sie im Polling-Muster.
2.7. Weiterführende Referenzen
-
POST startProcess Vollständige Parameterreferenz
-
GET getJobState: Antwortmodell und Statuswerte
-
GET getDocument: Dokumentabruf
-
Datenmodell der Job-Beschreibung: JSON-Referenz für jobDescription
3. Polling-Integrationsmuster
Das Polling-Integrationsmuster verwendet den Bulk-Abfrage-Endpunkt GET lookupJobStates, um periodisch alle Jobs abzurufen, die innerhalb eines Zeitfensters einen gewünschten Status erreicht haben. Dies macht einen Webhook-Endpunkt überflüssig und ermöglicht Ihrer Anwendung trotzdem, ohne manuelles Eingreifen auf abgeschlossene Signaturen zu reagieren.
3.1. Wann dieses Integrationsmuster verwendet werden sollte
-
Sie verfügen über MOXIS Business Cloud, welche keine Webhooks beinhaltet
-
Ihr Anwendungsendpunkt ist von MOXIS aus nicht erreichbar (z. B. hinter einer Firewall, im internen Netzwerk oder in einer Entwicklungsumgebung)
-
Sie bevorzugen aus Sicherheits- oder architektonischen Gründen ein Pull-basiertes Modell gegenüber einem eingehenden Endpunkt
-
Eine nahezu Echtzeit-Benachrichtigung ist akzeptabel (der Abschluss wird im nächsten Polling-Zyklus erkannt)
3.2. Funktionsweise
-
Ihre Anwendung erstellt einen Job mit POST startProcess und speichert die zurückgegebene processInstanceId (und optional eine eigene referenceId).
-
Ein zeitgesteuerter Job läuft in regelmäßigen Abständen und ruft GET lookupJobStates gefiltert nach FINISHED_SUCCESS und einem relevanten Zeitfenster auf.
-
Für jeden zurückgegebenen abgeschlossenen Job ruft Ihre Anwendung GET getDocument auf, um das signierte PDF abzurufen.
-
Der Zeitstempel der letzten Verarbeitung wird aktualisiert, um eine erneute Verarbeitung von Jobs im nächsten Durchlauf zu vermeiden.
3.3. Sequenzdiagramm
sequenceDiagram
participant App as Your App
participant Store as Your Data Store
participant Scheduler as Scheduler
participant API as MOXIS API
App->>API: POST /startProcess/{processId}
API-->>App: 201 Created — processInstanceId
App->>Store: Save processInstanceId + lastPolledAt
loop Every polling interval
Scheduler->>API: GET /lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=...&jobFinishedBefore=...
API-->>Scheduler: JSON array of completed jobs
loop For each completed job
Scheduler->>API: GET /getDocument/{processInstanceId}
API-->>Scheduler: Signed PDF (blob)
Scheduler->>Store: Save document, update lastPolledAt
end
end
3.4. Schritt-für-Schritt-Anleitung
3.4.1. Schritt 1: Job erstellen und ID speichern
POST https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/startProcess/{processId}
Authorization: Basic <base64(user:password)>
Content-Type: multipart/form-data
Der Response-Body ist die processInstanceId als reiner String (HTTP 201). Speichern Sie diesen Wert dauerhaft zusammen mit internen Kennungen. Wenn Sie eine referenceId in metaData übergeben, können Sie den Job später auch mit GET lookupJobStates?referenceId=... auffinden.
3.4.2. Schritt 2: Abgeschlossene Jobs abfragen
Verwenden Sie GET lookupJobStates mit einem Zeitfenster, um alle Jobs zu finden, die in einem bestimmten Zeitraum abgeschlossen wurden.
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=2026-04-23T00:00:00&jobFinishedBefore=2026-04-23T23:59:59
Authorization: Basic <base64(user:password)>
Wichtige Abfrageparameter:
|
Parameter |
Typ |
Beschreibung |
|
lookupStates |
string |
Kommagetrennte Liste von Statuswerten zur Filterung, z. B. FINISHED_SUCCESS oder FINISHED_SUCCESS,FINISHED_FAILED |
|
jobFinishedAfter |
string |
ISO 8601 — liefert Jobs, die nach diesem Zeitstempel abgeschlossen wurden |
|
jobFinishedBefore |
string |
ISO 8601 — liefert Jobs, die vor diesem Zeitstempel abgeschlossen wurden |
|
processIds |
string |
Filterung auf eine bestimmte Prozessvorlagen-ID |
|
referenceId |
string |
Filterung nach Ihrer eigenen Referenz-ID (MOXIS v4.52+) |
|
offset |
integer |
Paginierungs-Offset — Beginn des Ergebnisblocks (inklusiv) |
|
pageSize |
integer |
Anzahl der Ergebnisse pro Seite (Standard: 50) |
3.4.3. Beispielantwort:
[
{ "processInstanceId": "450123", "state": "FINISHED_SUCCESS" },
{ "processInstanceId": "450124", "state": "FINISHED_SUCCESS" }
]
lookupJobStates liefert nur processInstanceId und state. Für vollständige Job-Details rufen Sie GET getJobState für einzelne IDs auf.
3.4.4. Schritt 3: Paginierung behandeln
Die Standardseitengröße beträgt 50 Ergebnisse. Wenn Sie mehr abgeschlossene Jobs als das in einem einzelnen Zeitfenster erwarten, iterieren Sie mithilfe von offset und pageSize.
# First page (results 0–49)
GET /lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=...&offset=0&pageSize=50
# Second page (results 50–99)
GET /lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=...&offset=50&pageSize=50
Fordern Sie weiterhin Seiten an, bis das zurückgegebene Array kleiner als Ihre pageSize ist — das kennzeichnet die letzte Seite.
Um vor der Paginierung eine Gesamtanzahl zu ermitteln, verwenden Sie GET countLookupJobStates mit denselben Parametern:
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/countLookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=...
Liefert eine einzelne Ganzzahl mit der Gesamtzahl der übereinstimmenden Datensätze.
3.4.5. Schritt 4: Jedes signierte Dokument abrufen
Für jede processInstanceId in den Ergebnissen:
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getDocument/{processInstanceId}
Authorization: Basic <base64(user:password)>
Der Response-Body ist das signierte PDF als binäres Blob. Speichern Sie es in Ihrem Dokumentenspeicher.
3.4.6. Schritt 5: Zeitfenster verschieben
Aktualisieren Sie nach jedem Polling-Durchlauf Ihren gespeicherten lastPolledAt-Zeitstempel auf die aktuelle Zeit (oder auf den in diesem Durchlauf verwendeten Wert von jobFinishedBefore). Verwenden Sie diesen Wert im nächsten Durchlauf als jobFinishedAfter.
3.4.7. Beispiel Verschieben des Zeitfensters:
First run: jobFinishedAfter=2026-04-23T00:00:00 jobFinishedBefore=2026-04-23T01:00:00
Second run: jobFinishedAfter=2026-04-23T01:00:00 jobFinishedBefore=2026-04-23T02:00:00
Dies verhindert, dass dieselben abgeschlossenen Jobs über mehrere Polling-Zyklen hinweg erneut verarbeitet werden.
3.5. Polling für einen bestimmten, bekannten Job
Wenn Sie die processInstanceId bei der Erstellung gespeichert haben und nur einen bestimmten Job prüfen müssen, verwenden Sie direkt GET getJobState:
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobState/{processInstanceId}/{nameClassifier}
Authorization: Basic <base64(user:password)>
Dies liefert das vollständige Job-Status-Objekt. Prüfen Sie, ob state == "FINISHED_SUCCESS" und endDate != null sind, bevor Sie das Dokument herunterladen.
Falls Sie bei der Erstellung eine referenceId zugewiesen haben, verwenden Sie alternativ GET getJobStateByReferenceId:
GET https://<moxis-base-url>/webservices/rest/api/layer2/v1.0/getJobStateByReferenceId/{referenceId}/{nameClassifier}
3.6. Empfehlungen zur Polling-Häufigkeit
-
Mindestintervall:
Einmal pro Minute ist eine angemessene untere Grenze, um die API nicht zu überlasten und Abschlüsse trotzdem zeitnah zu erkennen.
-
An Ihre SLA anpassen:
Wenn Ihr Prozess erfordert, dass der Abschluss innerhalb von 5 Minuten verarbeitet wird, pollen Sie alle 1–2 Minuten mit einem entsprechenden Zeitfenster.
-
Überlappende Durchläufe vermeiden:
Stellen Sie sicher, dass jeder geplante Durchlauf abgeschlossen ist, bevor der nächste beginnt (insbesondere bei der Paginierung großer Ergebnismengen).
-
Enge Zeitfenster verwenden:
Die Abfrage eines 1-Stunden-Fensters alle 5 Minuten ist effizienter als die Abfrage unbegrenzter Ergebnisse.
3.7. Job-Status
|
Status |
Terminal? |
Beschreibung |
|
DRAFTING |
Nein |
Job ist ein Entwurf |
|
ACTIVE |
Nein |
Läuft, wartet auf Signatur(en) |
|
POST_PROCESSING |
Nein |
Signatur abgeschlossen, Nachbearbeitung läuft |
|
FINISHED_SUCCESS |
Ja |
Alle Signaturen erfolgreich eingeholt |
|
FINISHED_FAILED |
Ja |
Signatur fehlgeschlagen |
|
FINISHED_TIMEOUT |
Ja |
Job abgelaufen |
|
FINISHED_WF_CANCELLED |
Ja |
Workflow abgebrochen |
|
FINISHED_SIGNATURE_DENIED |
Ja |
Signer hat das Dokument abgelehnt |
|
DRAFT_DISMISSED |
Ja |
Entwurf verworfen |
3.8. Beispiel: vollständiger Polling-Zyklus
# 1. Count completed jobs in window to determine pagination needs
GET /countLookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=2026-04-23T13:00:00&jobFinishedBefore=2026-04-23T14:00:00
→ 3
# 2. Retrieve all completed jobs (3 < 50, no pagination needed)
GET /lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=2026-04-23T13:00:00&jobFinishedBefore=2026-04-23T14:00:00
→ [
{ "processInstanceId": "450123", "state": "FINISHED_SUCCESS" },
{ "processInstanceId": "450124", "state": "FINISHED_SUCCESS" },
{ "processInstanceId": "450125", "state": "FINISHED_SUCCESS" }
]
# 3. Download each document
GET /getDocument/450123 → contract-a.pdf
GET /getDocument/450124 → contract-b.pdf
GET /getDocument/450125 → contract-c.pdf
# 4. Store documents, advance lastPolledAt to 2026-04-23T14:00:00
3.9. Weiterführende Referenzen
-
GET lookupJobStates: Vollständige Parameterreferenz und Antwortmodell
-
GET countLookupJobStates: Anzahl vor der Paginierung ermitteln
-
GET getJobState: Detaillierter Status für einen einzelnen Job
-
GET getDocument: Signiertes Dokument abrufen
-
POST createJob: Jobs mit referenceId erstellen
4. Webhook-Integration
MOXIS kann Job-Status-Events an einen von Ihnen kontrollierten HTTPS-Endpunkt senden. Sobald ein Job einen konfigurierten Trigger-Status erreicht, sendet MOXIS eine HTTP-POST-Anfrage an Ihren Endpunkt mit einem JSON-Payload, das den vollständigen Job-Status enthält. Ihre Anwendung reagiert dann auf das Event (üblicherweise durch Aufruf von GET getDocument, um die signierte Datei abzurufen).
4.1. Wann dieses Muster verwendet werden sollte
-
Sie verfügen über MOXIS Enterprise Cloud (Webhooks sind bei Business Cloud nicht verfügbar)
-
Sie möchten Signaturereignisse in Echtzeit benachrichtigt bekommen, ohne zu pollen
-
Ihre Anwendung verfügt über einen öffentlich erreichbaren HTTPS-Endpunkt
-
Sie erstellen eine produktive, ereignisgesteuerte Integration
4.2. Voraussetzungen
-
Ein von MOXIS aus erreichbarer HTTPS-Endpunkt mit einem gültigen SSL-Zertifikat
-
Ein MOXIS-Administrator, der den Webhook pro Prozess in der MOXIS-Administrationsoberfläche konfigurieren kann
-
Zugangsdaten für Ihren Endpunkt (Basic Auth oder OAuth Client Credentials) oder eine bewusste Entscheidung, eine unauthentifizierte Zustellung zu akzeptieren
4.3. Konfiguration
Webhooks werden pro Prozess von einem MOXIS-Administrator im Bereich der Prozesskonfiguration der Administrationsoberfläche eingerichtet. Der Administrator gibt Folgendes an:
-
Die Ziel-Endpunkt-URL (HTTPS erforderlich)
-
Die Authentifizierungsmethode: Basic-Auth-Zugangsdaten, OAuth 2.0 client_credentials oder keine Authentifizierung
-
Den/die Trigger-Ereignistyp(en), die den Webhook auslösen sollen
Umgang mit SSL-Zertifikaten:
Bei der ersten erfolgreichen Verbindung speichert MOXIS das von Ihrem Endpunkt präsentierte SSL-Zertifikat. Nachfolgende Zustellungen werden gegen dieses gespeicherte Zertifikat validiert. Wenn das Zertifikat abläuft oder ersetzt wird, muss der Administrator den Webhook mit dem neuen Zertifikat neu konfigurieren.
4.4. Trigger-Ereignisse
Webhook-Trigger werden als nicht final (der Job wird nach dem Ereignis fortgesetzt) und final (der Job hat einen Endstatus erreicht) klassifiziert.
4.4.1. Nicht finale Trigger
|
Trigger |
Beschreibung |
|
Invited |
Ein Signer wurde zum Job eingeladen |
|
Signed |
Ein einzelner Signer hat seine Signatur abgeschlossen |
|
Changed Iteration |
Der Job ist zur nächsten Iteration übergegangen |
|
Before Signature |
Wird unmittelbar vor dem Anbringen einer Signatur ausgelöst |
|
Expiry Date Changed |
Das Verfallsdatum des Jobs wurde geändert |
4.4.2. Finale Trigger
|
Trigger |
Beschreibung |
|
Finished Successfully |
Alle Signaturen sind eingeholt, das Dokument ist bereit. |
|
Declined |
Ein Signierender hat die Signatur abgelehnt. |
|
Aborted |
Der Job wurde abgebrochen. |
|
Expired |
Der Job hat sein Verfallsdatum ohne Abschluss erreicht. |
|
Denied Draft |
Ein Entwurf wurde vor Start des Jobs abgelehnt. |
MOXIS Tipp
Konfigurieren Sie den Webhook für die meisten Integrationen so, dass er nur bei finalen Ereignistypen auslöst. Dies begrenzt das Zustellvolumen und stellt sicher, dass Sie nur bei einem endgültigen Ergebnis reagieren. Rufen Sie beim Empfang eines Finished Successfully-Events GET getDocument auf, um das signierte PDF abzurufen.
4.5. Feststellen des Jobabschlusses
Ein Job ist endgültig abgeschlossen und das Dokument ist bereit, wenn beide der folgenden Bedingungen im Webhook-Payload erfüllt sind:
-
state ist gleich FINISHED_SUCCESS
-
endDate ist nicht null
Prüfen Sie beide Felder. state allein reicht nicht aus — ein gesetztes endDate bestätigt, dass die serverseitige Nachbearbeitung abgeschlossen ist.
{
"state": "FINISHED_SUCCESS",
"endDate": "2026-04-23T14:30:00Z",
...
}
4.6. Webhook-Payload-Schema
Das an Ihren Endpunkt gesendete Payload ist ein JSON-Objekt. Alle String-Felder können null sein. Das Schema entspricht der Antwort von GET getJobState.
{
"type": "object",
"properties": {
"state": { "type": "string" },
"processId": { "type": "string" },
"processInstanceId": { "type": "integer" },
"jobMetaData": {
"type": "object",
"properties": {
"description": { "type": "string" },
"category": {},
"expirationDate": { "type": "string" },
"referenceId": {},
"customMap": { "type": "object", "properties": {} },
"externalPassword": {}
}
},
"creationDate": { "type": "string" },
"endDate": { "type": "string" },
"currentIteration": { "type": "integer" },
"iterations": {
"type": "array",
"items": {},
"required": [
"numberOfSignatures",
"invitees",
"category",
"iterationNumber",
"remark",
"signerGroup",
"privateIteration",
"customMap",
"groupPositions"
]
},
"additionalRecipients": { "type": "array" },
"constituent": { "type": "string" },
"customMap": { "type": "object", "properties": {} },
"eventTimestamp": { "type": "string" },
"eventType": { "type": "string" }
}
}
4.6.1. Wichtige Felder
|
Feld |
Typ |
Beschreibung |
|
state |
string |
Aktueller Job-Status (siehe Statustabelle unten) |
|
processInstanceId |
integer |
Eindeutige Kennung dieses Jobs — verwenden Sie diese für nachfolgende API-Methodenaufrufe |
|
endDate |
string |
ISO-8601-Zeitstempel, der gesetzt wird, wenn der Job einen Endstatus erreicht; null, solange der Job aktiv ist |
|
eventType |
string |
Das Trigger-Ereignis, das diese Zustellung ausgelöst hat |
|
eventTimestamp |
string |
Zeitpunkt, zu dem das Ereignis eingetreten ist |
|
iterations |
array |
Details auf Iterationsebene, einschließlich der Ergebnisse einzelner Eingeladener |
4.6.2. Job-Status
|
Status |
Terminal? |
Beschreibung |
|
DRAFTING |
Nein |
Job ist ein Entwurf |
|
ACTIVE |
Nein |
Läuft, wartet auf Signatur(en) |
|
POST_PROCESSING |
Nein |
Signatur abgeschlossen, MOXIS-Nachbearbeitung läuft |
|
FINISHED_SUCCESS |
Ja |
Alle Signaturen erfolgreich eingeholt |
|
FINISHED_FAILED |
Ja |
Signatur fehlgeschlagen |
|
FINISHED_TIMEOUT |
Ja |
Job vor Abschluss abgelaufen |
|
FINISHED_WF_CANCELLED |
Ja |
Workflow abgebrochen |
|
FINISHED_SIGNATURE_DENIED |
Ja |
Ein Signer hat das Dokument abgelehnt |
|
DRAFT_DISMISSED |
Ja |
Entwurf wurde verworfen |
4.7. Prüfen einzelner Signaturergebnisse
Um festzustellen, welche Aktion ein bestimmter Signer durchgeführt hat, prüfen Sie iterations[].invitees[].action im Payload. Dieses Feld spiegelt das individuelle Ergebnis für jeden Eingeladenen wider.
{
"iterations": [
{
"iterationNumber": 0,
"invitees": [
{
"name": "signer@example.com",
"action": "SIGNED",
"actionDate": "2026-04-23T14:28:00Z"
}
]
}
]
}
Häufige Werte für action sind SIGNED, DECLINED und null (noch keine Aktion durchgeführt).
4.8. Integrationsablauf
sequenceDiagram
participant App as Your App
participant API as MOXIS API
participant MOXIS as MOXIS
participant Endpoint as Your Webhook Endpoint
App->>API: POST /startProcess/{processId}
API-->>App: 201 Created — processInstanceId
Note over MOXIS: Signer completes signature in MOXIS UI
MOXIS->>Endpoint: POST {webhookPayload} (final event)
Endpoint-->>MOXIS: HTTP 200 OK
Endpoint->>App: Forward event or trigger downstream logic
App->>API: GET /getDocument/{processInstanceId}
API-->>App: Signed PDF (blob)
4.9. Sicherheitsaspekte
4.9.1. Authentifizierung eingehender Webhook-Anfragen
Konfigurieren Sie Basic Auth oder OAuth client_credentials für Ihren Endpunkt. MOXIS übermittelt die Zugangsdaten in jeder Anfrage. Ihr Endpunkt muss diese Zugangsdaten validieren und Anfragen ablehnen, die nicht übereinstimmen.
Wenn Sie sich entscheiden, keine Authentifizierung zu verlangen (möglich, aber nicht empfohlen), stellen Sie sicher, dass andere Kontrollen vorhanden sind — zum Beispiel eine IP-Zulassungsliste für die Egress-Adressen von MOXIS.
4.9.2. SSL-Zertifikatsvertrauen
MOXIS vertraut dem bei der ersten Verbindung beobachteten SSL-Zertifikat. Das bedeutet:
-
Ihr Endpunkt muss von Anfang an ein gültiges Zertifikat präsentieren.
-
Wenn Ihr Zertifikat erneuert oder ersetzt wird, muss der MOXIS-Administrator die Webhook-Konfiguration aktualisieren, damit das neue Zertifikat hinterlegt wird.
-
Abgelaufene Zertifikate führen zu Zustellfehlern, bis die Konfiguration angepasst wird.
4.9.3. Reagieren auf Zustellungen
Geben Sie so schnell wie möglich den HTTP-Status 200 zurück. Führen Sie aufwendige Verarbeitungsschritte asynchron durch, nachdem der Empfang bestätigt wurde. Wenn Ihr Endpunkt einen Nicht-2xx-Status zurückgibt, kann MOXIS die Zustellung wiederholen (das Verhalten hängt von Ihrer MOXIS-Konfiguration ab).
4.10. Beispiel: Empfangen und Verarbeiten eines Webhooks
POST /moxis-webhook HTTP/1.1
Host: your-app.example.com
Authorization: Basic <base64(webhookUser:webhookPassword)>
Content-Type: application/json
{
"state": "FINISHED_SUCCESS",
"processInstanceId": 450123,
"endDate": "2026-04-23T14:30:00Z",
"eventType": "Finished successfully",
"eventTimestamp": "2026-04-23T14:30:01Z",
"jobMetaData": {
"referenceId": "CONTRACT-00123",
"description": "Contract review Q2 2026"
},
"iterations": [
{
"iterationNumber": 0,
"invitees": [
{
"name": "signer@example.com",
"action": "SIGNED",
"actionDate": "2026-04-23T14:28:00Z"
}
]
}
]
}
4.10.1. Verarbeitungslogik:
-
Basic-Auth-Header validieren — bei Ungültigkeit mit 401 ablehnen.
-
Prüfen, ob state == "FINISHED_SUCCESS" und endDate != null.
-
processInstanceId extrahieren (oder referenceId aus jobMetaData, falls Sie eigene Referenzen verwenden).
-
Sofort mit 200 OK antworten.
-
Asynchron GET /getDocument/{processInstanceId} aufrufen und das Ergebnis speichern.
4.11. Weiterführende Referenzen
-
GET getJobState: Dasselbe Datenmodell wie das Webhook-Payload
-
GET getDocument: Signiertes Dokument abrufen
-
POST createJob: Job erstellen, um den Workflow auszulösen
-
Authentifizierung: Einrichtung der API-Zugangsdaten
5. Middleware-Muster
Wenn mehrere interne Anwendungen mit MOXIS interagieren müssen, ist es unpraktikabel, in jeder von ihnen eine eigene direkte Integration zu implementieren und zu pflegen. Eine Middleware-Schicht (ein dedizierter Integrationsdienst) verwaltet die Verbindung zur MOXIS API und stellt den aufrufenden Anwendungen eine vereinfachte interne API zur Verfügung.
5.1. Wann dieses Muster verwendet werden sollte
-
Mehrere interne Anwendungen (CRM, ERP, DMS, individuelle Anwendungen) müssen Dokumente zur Signatur versenden
-
Sie möchten Zugangsdaten und Änderungen am API-Endpunkt an einer einzigen, zentral verwalteten Stelle pflegen
-
Aufrufende Anwendungen verfügen über eingeschränkte API-Fähigkeiten oder sind standardisierte Produkte ohne Spielraum für individuelle ausgehende HTTP-Logik
-
Sie möchten die fachliche Komplexität entkoppeln: Aufrufende Anwendungen sollen nichts über MOXIS-Job-Status, Prozess-IDs oder Iterationsmodelle wissen müssen
-
Sie benötigen gemeinsame Belange (Logging, Wiederholungslogik, Fehlerbehandlung, Audit-Trails) die konsistent über alle Aufrufer angewendet werden
5.2. Architekturübersicht
graph TD
A[App A<br/>CRM] -->|Internal API call| MW[Middleware<br/>Integration Service]
B[App B<br/>DMS] -->|Internal API call| MW
C[App C<br/>ERP] -->|Internal API call| MW
MW -->|REST API| MOXIS[MOXIS API]
MOXIS -->|Webhook or polling| MW
MW -->|Event / callback| A
MW -->|Event / callback| B
MW -->|Event / callback| C
Aufrufende Anwendungen interagieren ausschließlich mit der internen API der Middleware. Die Middleware übersetzt diese Aufrufe in MOXIS-API-Anfragen, übernimmt die Authentifizierung, überwacht den Job-Status und liefert die Ergebnisse an die ursprüngliche Anwendung zurück.
5.3. Aufgaben der Middleware
Verwaltung der Zugangsdaten
Die Middleware hält die Zugangsdaten des MOXIS-Webservice-Benutzers (Basic Auth oder OAuth-Tokens) an einer einzigen Stelle. Wenn Zugangsdaten rotiert werden oder sich ein OAuth-Client-Secret ändert, muss nur die Middleware aktualisiert werden — die aufrufenden Anwendungen sind davon nicht betroffen.
Anfrage-Routing
Unterschiedliche Prozesse in MOXIS entsprechen unterschiedlichen Signatur-Workflows. Die Middleware bildet einen internen Anfragetyp (z. B. „Vertragsfreigabe“ oder „HR-Onboarding-Formular“) auf die passende MOXIS-processId ab, erstellt das jobDescription-JSON und ruft POST startProcess auf.
Job-Tracking
Die Middleware speichert die von MOXIS zurückgegebene processInstanceId (und optional eine referenceId) zusammen mit der internen Datensatz-ID der ursprünglichen Anwendung. Dies ist die Verknüpfung zwischen dem externen MOXIS-Job und dem internen fachlichen Kontext.
Event-Zustellung (Webhook-Modus)
Wenn MOXIS auf Enterprise Cloud läuft, registriert die Middleware einen einzigen Webhook-Endpunkt. Beim Empfang eines finalen Events führt die Middleware Folgendes aus:
-
Validierung der eingehenden Anfrage (Basic Auth oder OAuth)
-
Nachschlagen des mit der processInstanceId verknüpften internen Datensatzes
-
Aufruf von GET getDocument zum Abrufen des signierten PDFs
-
Zustellung des Ergebnisses an die ursprüngliche Anwendung über einen internen Event-Bus, Callback oder direkten API-Aufruf
Event-Zustellung — Polling-Modus
Wenn Webhooks nicht verfügbar sind (z.B. in der MOXIS Business Cloud), betreibt die Middleware einen Scheduler, der in regelmäßigen Abständen GET lookupJobStates aufruft, Paginierung anwendet, Dokumente für abgeschlossene Jobs abruft und Ergebnisse intern verteilt. Die Abfragestrategie ist im Polling-Muster beschrieben.
Wiederholungslogik
Vorübergehende Fehler — Netzwerk-Timeouts, MOXIS-500-Fehler, Nichtverfügbarkeit einer nachgelagerten Anwendung — werden von der Middleware mittels exponentiellem Backoff behandelt. Aufrufende Anwendungen müssen keine eigene Wiederholungslogik implementieren.
Logging und Audit
Alle ausgehenden API-Aufrufe an MOXIS sowie alle eingehenden Events werden zentral protokolliert. Dies liefert einen vollständigen Audit-Trail der Dokumentenlebenszyklus-Ereignisse über alle aufrufenden Anwendungen hinweg.
Fehlerbehandlung
Die Middleware normalisiert MOXIS-Fehlerantworten (400, 404, 500) und übersetzt sie in konsistente Fehlercodes für die aufrufenden Anwendungen.
5.4. Integrationsablauf
Webhook-Variante
sequenceDiagram
participant AppA as App A
participant MW as Middleware
participant API as MOXIS API
participant MOXIS as MOXIS
participant Endpoint as Middleware Webhook Endpoint
AppA->>MW: createSigningRequest(docId, signerEmail)
MW->>API: POST /startProcess/{processId}
API-->>MW: 201 Created — processInstanceId
MW->>MW: Store docId → processInstanceId mapping
Note over MOXIS: Signer completes signature
MOXIS->>Endpoint: POST webhook payload (FINISHED_SUCCESS)
Endpoint-->>MOXIS: 200 OK
MW->>API: GET /getDocument/{processInstanceId}
API-->>MW: Signed PDF
MW->>AppA: Deliver signed PDF / fire internal event
Polling-Variante
sequenceDiagram
participant AppA as App A
participant MW as Middleware
participant API as MOXIS API
participant Scheduler as Scheduler
AppA->>MW: createSigningRequest(docId, signerEmail)
MW->>API: POST /startProcess/{processId}
API-->>MW: 201 Created — processInstanceId
MW->>MW: Store docId → processInstanceId mapping
loop Every polling interval
Scheduler->>API: GET /lookupJobStates?lookupStates=FINISHED_SUCCESS&jobFinishedAfter=...
API-->>Scheduler: Array of completed jobs
loop For each completed job
Scheduler->>API: GET /getDocument/{processInstanceId}
API-->>Scheduler: Signed PDF
Scheduler->>AppA: Deliver signed PDF / fire internal event
end
end
5.5. Design der internen API
Die Middleware sollte den aufrufenden Anwendungen eine einfachere Schnittstelle bereitstellen. Eine minimale interne API könnte Folgendes umfassen:
|
Interner Endpunkt |
Beschreibung |
|
POST /sign |
Dokument zur Signatur einreichen. Akzeptiert ein Dokument-Blob und Metadaten; liefert eine interne Job-ID zurück |
|
GET /sign/{internalJobId} |
Status eines Signaturjobs über die interne ID abfragen |
|
GET /sign/{internalJobId}/document |
Signiertes Dokument nach Abschluss abrufen |
|
POST /sign/{internalJobId}/cancel |
Einen laufenden Job abbrechen |
Aufrufende Anwendungen sehen niemals processInstanceId, processId, iterationData oder ein anderes MOXIS-spezifisches Konzept. Sie arbeiten ausschließlich mit dem internen Domänenmodell.
5.6. Vorteile
-
Zentraler Aktualisierungspunkt:
Rotation von Zugangsdaten, Änderungen der Endpunkt-URL oder API-Versionsupgrades erfolgen an einer einzigen Stelle
-
Vereinfachte Aufrufer:
App A muss überhaupt nicht wissen, dass die Signatur über MOXIS abgewickelt wird
-
Konsistentes Verhalten:
Wiederholungslogik, Logging und Fehlerbehandlung werden einheitlich angewendet
-
Flexibles Event-Modell: Die Middleware kann Webhook und Polling gleichzeitig unterstützen. Dies ist nützlich bei der Migration zwischen MOXIS Varianten oder Umgebungen
-
Testbarkeit: Aufrufende Anwendungen können gegen eine simulierte Middleware getestet werden, ohne eine aktive MOXIS-Verbindung
5.7. Hinweise zur Implementierung
Postman-Collection als leichtgewichtige Middleware
MOXIS stellt eine Postman-Collection für die MOXIS API bereit. Für Tests und interne Evaluierungen fungiert die Postman-Collection als minimale Ausprägung dieses Musters. Sie abstrahiert die rohen HTTP-Aufrufe hinter benannten Requests und Umgebungsvariablen. Sie ist nicht für den Produktionseinsatz geeignet, aber ein nützlicher Ausgangspunkt, um die API zu verstehen, bevor eine echte Middleware aufgebaut wird.
Technologieauswahl
Die Middleware kann implementiert werden als: - Ein dedizierter Microservice (Node.js, Java, .NET, Python) - Eine Integrationsplattform (MuleSoft, Azure Logic Apps, Apache Camel) - Eine Sammlung serverloser Funktionen mit einer Warteschlange für das Job-Tracking
Die MOXIS API stellt keine Anforderungen an die Middleware-Technologie. Sie kommuniziert über Standard-HTTPS mit Basic Auth oder OAuth 2.0 (client_credentials).
Idempotenz
Speichern Sie die von MOXIS zurückgegebene processInstanceId sofort nach POST startProcess. Wenn der Aufruf erfolgreich ist, Ihre Middleware jedoch abstürzt, bevor die ID gespeichert wird, müssen Sie den Job möglicherweise mit GET lookupJobStates über eine referenceId oder ein Zeitfenster wiederherstellen. Weisen Sie bei der Job-Erstellung eine referenceId aus Ihrem eigenen System zu, um die Wiederherstellung deterministisch zu gestalten.
5.8. Weiterführende Referenzen
-
Webhook-Integration: Ereignisbasierte Abschlussbenachrichtigung
-
Polling-Muster: Zeitgesteuerte Abschlusserkennung
-
POST createJob: Job-Erstellung mit referenceId
-
GET lookupJobStates: Bulk-Abfragen des Job-Status
-
GET getDocument: Dokumentabruf
-
Authentifizierung: Einrichtung von Basic Auth und OAuth