Dokumentation

Webhooks-Übersicht

Erhalten Sie Echtzeit-Benachrichtigungen über Ereignisse in Ihrem Parsurai-Konto.

Mit Parsurai-Webhooks kann Ihre Anwendung HTTP-POST-Benachrichtigungen in Echtzeit empfangen, wenn Ereignisse in Ihrem Konto auftreten, z. B. wenn eine Rechnungsprüfung abgeschlossen oder eine manuelle Prüfung beendet ist.

Unterstützte Ereignistypen

EreignistypBeschreibung
extraction.completedEin Rechnungsdokument wurde erfolgreich verarbeitet und strukturierte Daten wurden extrahiert.
extraction.failedDie Verarbeitung eines Rechnungsdokuments ist aufgrund eines Parsing-Fehlers oder eines unleserlichen Layouts fehlgeschlagen.
review.requiredEine manuelle Überprüfung ist erforderlich, da das Vertrauensniveau der Extraktion unter dem Schwellenwert lag.
review.completedEin menschlicher Prüfer hat die manuelle Verifizierung abgeschlossen und die Rechnungsfelder finalisiert.
workflow.completedDie gesamte Dokumenten-Pipeline (einschließlich optionalem Zuschneiden, Teilen und Prüfen) war erfolgreich.
workflow.failedDie Pipeline wurde abgebrochen, da eine der obligatorischen Verarbeitungsstufen fehlgeschlagen ist.

Payload-Struktur (Umschlag)

Alle Webhooks werden als application/json HTTP-POST-Anfragen gesendet. Der Anfragetext enthält ein JSON-Objekt, das die Ereignismetadaten und die spezifischen Ressourcendaten umschließt.

{
  "id": "evt_9f3b2c1d0e4a4f5b8c6d7e8f9a0b1c2d",
  "type": "extraction.completed",
  "version": "2026-06-01",
  "occurred_at": "2026-06-21T10:40:00Z",
  "tenant_id": "7f9c2f4e-9b1a-4c3d-8e5f-6a7b8c9d0e1f",
  "data": {
    "invoice_id": "a3a4c1de-1c1e-4b6f-9d2a-0f8e7d6c5b4a"
  }
}

Felder auf oberster Ebene

  • id: Ein eindeutiger Bezeichner für dieses Ereignis (evt_...). Wird zur Duplikaterkennung verwendet.
  • type: Die Ereignistyp-Zeichenkette (z.B. extraction.completed).
  • version: Die API-Umschlagversion, die der Konfiguration des Benutzers entspricht.
  • occurred_at: ISO-8601 UTC-Zeitstempel des ursprünglichen Ereignisses.
  • tenant_id: Die ID Ihres Parsurai-Kontos/Mandanten.
  • data: Ein Datenobjekt mit Referenzen oder Metadaten, die für das Ereignis relevant sind. Zum Schutz sensibler Kundendaten minimieren ausgehende Webhook-Payloads PII und enthalten nur Ressourcen-IDs. Sie können die vollständigen Ressourcendetails über unsere REST-API oder SDKs abfragen.

Zustellungsrichtlinien & Sicherheit

  • HTTPS-Protokoll: In der Produktionsumgebung stellt Parsurai Webhooks nur an sichere https://-URLs zu.
  • Portbeschränkung: Produktions-Endpunkte müssen auf Port 443 (explizit oder implizit) lauschen. Andere Ports werden abgelehnt, um Server-Side Request Forgery (SSRF) zu verhindern.
  • Keine statischen IP-Adressen: Parsurai leitet ausgehende Webhooks nicht über einen statischen IP-Adressblock weiter. Sie sollten die Anfragesignaturen überprüfen, anstatt IPs auf eine weiße Liste zu setzen.
  • Lease und Timeout: Wir erwarten, dass Ihr Server innerhalb von 10 Sekunden (Verbindung/Lesen) mit einem 2xx-Statuscode antwortet. Andernfalls wird ein Wiederholungsversuch eingeleitet.
  • Soft-Delete-Historie: Gelöschte Webhook-Endpunkte werden als soft-deleted markiert. Die Historie bleibt für Audits erhalten, bis die Aufbewahrungsfrist sie endgültig entfernt.
  • Idempotenz: Webhooks werden mindestens einmal zugestellt. Ihr Empfänger muss redundant eintreffende Nachrichten anhand der id filtern.