Developers
OpenAPI ↗
Zur App
Dokumentation / Integrationen
API v1 · Integrationen

Webhooks integrieren

Signierte Benachrichtigungen sicher in Ihr ERP oder Ihre Anwendung integrieren.

Auf dieser Seite
Ein Abschlussereignis statt wiederholter Statusabfragen

Rebilix sendet Ihrem Server eine signierte HTTP-Anfrage, sobald ein Hintergrundauftrag endet. Ihr Server bestätigt den sicheren Empfang und verarbeitet das Ereignis anschließend.

Rebilix-AuftragSignierter POST → ERPInbox speichernHTTP 200

In fünf Schritten zur Integration

  1. Stellen Sie einen öffentlich erreichbaren Receiver bereit, zum Beispiel https://erp.example.com/webhooks/rebilix.
  2. Öffnen Sie Integration → Aufträge & Webhooks, wählen Sie Sandbox oder Live und legen Sie den Empfänger an. Maximal fünf aktive Empfänger je Umgebung.
  3. Speichern Sie das einmal angezeigte whsec_…-Geheimnis im Secret Store des Receivers.
  4. Starten Sie einen Hintergrundauftrag und speichern Sie dessen Job-ID bei Ihrem ERP-Datensatz.
  5. Prüfen Sie Signatur und Kontext, speichern Sie das Ereignis dauerhaft und bestätigen Sie mit 2xx. Ein ERP-Worker ruft danach das aktuelle Ergebnis ab.

Für einen vollständigen Startpunkt verwenden Sie den ausführbaren ASP.NET Core Receiver mit SQL Server.

Was Ihr Endpoint erfüllen muss

AnforderungVerhalten
HTTPS · Port 443Öffentlicher DNS-Hostname und gültiges TLS-Zertifikat. Keine IP-Literale, Zugangsdaten, Query-Parameter oder URL-Fragmente.
POST · application/jsonOriginalbytes bis höchstens 64 KiB lesen; vor der Signaturprüfung nicht deserialisieren oder neu formatieren.
Direkte AntwortKeine Login-Seite und keine Weiterleitung. Die Signatur authentifiziert die Anfrage, nicht eine ERP-Browsersitzung.
Schnell bestätigenNach Datenbank-Commit mit 2xx antworten. Rebilix wartet höchstens 15 Sekunden auf die HTTP-Antwort.
Öffentlich erreichbarPrivate / interne Ziele werden auch nach DNS-Auflösung blockiert. localhost kann nicht direkt als Empfänger registriert werden.

Ereignisse und Payload

Aktive Empfänger derselben Umgebung erhalten job.succeeded oder job.failed. Zwischenzeitliche automatische Retries lösen kein Abschlussereignis aus. Neue Empfänger erhalten keine historischen Ereignisse.

JSON · job.succeeded
{
  "id": "18e7ba7a-7565-4d07-b980-a068d397ff13",
  "type": "job.succeeded",
  "environment": "sandbox",
  "createdAt": "2026-11-01T10:15:00+00:00",
  "version": 1,
  "workspaceId": "11111111-1111-4111-8111-111111111111",
  "jobId": "22222222-2222-4222-8222-222222222222",
  "operation": "validate",
  "state": "succeeded",
  "resultStatus": "valid",
  "documentId": "33333333-3333-4333-8333-333333333333",
  "conversionReviewId": null,
  "errorCode": null
}
FeldBedeutung
idEreignis-UUID. Bleibt bei Zustellwiederholungen gleich.
type / statejob.succeeded / succeeded oder job.failed / failed.
environmentsandbox oder live; muss zur Receiver-Konfiguration passen.
createdAtZeitpunkt des terminalen Ereignisses, nicht des aktuellen Zustellversuchs.
versionPayload-Schema, aktuell 1. Änderungen bewusst behandeln.
workspaceIdArbeitsbereich des Auftrags. Mit dem erwarteten Mandanten vergleichen.
jobId / operationAuftrag und Aktion: generate, parse, validate oder conversion-review.
resultStatusvalid, invalid, not_checked, ready oder blocked; bei Verarbeitungsfehlern null.
documentIdReferenz auf gespeichertes Dokument; andernfalls null.
conversionReviewIdReferenz auf Konvertierungsprüfung; andernfalls null.
errorCodeTechnischer Fehlercode bei job.failed; bei Erfolg null.
job.succeeded ist keine Rechnungsfreigabe.

Auch resultStatus: invalid oder blocked kann zu einem abgeschlossenen Auftrag gehören. Das Ereignis enthält keine Rechnungsdateien, Kundendaten oder API-Schlüssel.

JSON · job.failed
{
  "id": "9c692ed6-a07b-49a8-aeb6-10a84c749149",
  "type": "job.failed",
  "environment": "sandbox",
  "createdAt": "2026-11-01T10:18:00+00:00",
  "version": 1,
  "workspaceId": "11111111-1111-4111-8111-111111111111",
  "jobId": "22222222-2222-4222-8222-222222222222",
  "operation": "validate",
  "state": "failed",
  "resultStatus": null,
  "documentId": null,
  "conversionReviewId": null,
  "errorCode": "validation_unavailable"
}

Signatur anhand der Originalbytes prüfen

HeaderZweck
X-Rebilix-Event-IdStabile Ereignis-ID; nach Prüfung mit payload.id vergleichen.
X-Rebilix-Delivery-IdZustellung für dieses Ereignis / diesen Empfänger. Nur zur Korrelation; nicht als Deduplizierungsschlüssel verwenden.
X-Rebilix-TimestampUnix-Sekunden, für jeden Versuch neu gesetzt.
X-Rebilix-Signaturev1= gefolgt von 64 Hex-Zeichen.

Berechnen Sie HMAC-SHA256 über UTF-8 timestamp + "." + eventId + ".", unmittelbar gefolgt von den unveränderten JSON-Bytes. Der HMAC-Schlüssel ist die exakte UTF-8-Zeichenfolge whsec_…; nicht als Hex oder Base64 decodieren.

C# · Rebilix.Sdk
using Rebilix.Sdk;

// rawBody: begrenzter Request-Body, noch nicht deserialisiert.
bool authentic = RebilixWebhook.Verify(
    rawBody,
    request.Headers["X-Rebilix-Event-Id"].ToString(),
    request.Headers["X-Rebilix-Timestamp"].ToString(),
    request.Headers["X-Rebilix-Signature"].ToString(),
    signingSecret);

if (!authentic)
    return Results.Unauthorized();

// Danach Kontext prüfen und in einer dauerhaften Inbox speichern.
// Vollständiger Receiver: SDK & Beispiele → ZIP herunterladen.

Der SDK vergleicht die Signatur in konstanter Zeit und erlaubt höchstens fünf Minuten Zeitabweichung. Halten Sie die Serveruhren synchron. Erst nach erfolgreicher Prüfung JSON lesen und Ereignis-ID, Arbeitsbereich, Umgebung, Version und Ereignistyp validieren.

Der Lieferungs-ID-Header gehört nicht zur signierten Zeichenfolge. Die signierte Ereignis-ID zusammen mit dem Payload ist die Grundlage der Verarbeitung.

Zuverlässig empfangen und verarbeiten

  1. Signatur falsch / Zeitfenster abgelaufen: mit 401 ablehnen, keine ERP-Daten ändern.
  2. Gültiges neues Ereignis: Originalpayload und Ereignis-ID in einer persistenten Inbox speichern. Ein eindeutiger Datenbankindex verhindert parallele Duplikate.
  3. Identisches bereits gespeichertes Ereignis: erneut 2xx zurückgeben, keine zweite Geschäftsaktion ausführen.
  4. Datenbank-Commit fehlgeschlagen: keinen Erfolg bestätigen. Eine 5xx-Antwort ermöglicht Rebilix die Wiederholung.
  5. Nach dem Commit: 200 oder 204 antworten. Ein eigener Worker liest Jobstatus und Ergebnisse mit einem API-Schlüssel und aktualisiert den zugeordneten ERP-Datensatz.

ERP-Änderung und „verarbeitet“-Markierung gehören in dieselbe Transaktion. Für externe Folgewirkungen verwenden Sie eine eigene transaktionale Outbox. Eine Hintergrundaufgabe ohne dauerhafte Speicherung reicht nicht aus.

Reihenfolge und Duplikate berücksichtigen

Ereignisse können mehrfach und in anderer Reihenfolge eintreffen. Eine manuell erneut gestartete Verarbeitung kann später ein neues Abschlussereignis erhalten. Lesen Sie den aktuellen Jobstatus, damit ein altes Fehlerereignis keinen neueren Erfolg überschreibt.

Zustellung und Wiederholungen

Antwort / SituationRebilix-Verhalten
2xxAls zugestellt markieren.
Netzwerkfehler, 408, 429, 5xxAutomatisch wiederholen: 30 / 60 / 120 / 240 Sekunden. Retry-After kann die Wartezeit bis zu einer Stunde verlängern.
Andere HTTP-StatuscodesAutomatische Wiederholung stoppen. Nach Fehlerbehebung gegebenenfalls ausdrücklich erneut zustellen.
Verbindungsabbruch nach EmpfangErgebnis kann unbekannt sein. Doppelte Zustellung ist möglich.

Bis zu fünf Versuche je Zyklus, insgesamt höchstens zwanzig gestartete Zustellversuche. Es gibt keine Exactly-once- oder unbegrenzte Zustellgarantie. Fehlgeschlagene Zustellungen überwachen.

Unter Integration → Aufträge & Webhooks stehen Payload, Versuchszähler, HTTP-Status und Signatur-Header. Die API bietet GET /webhook-deliveries und GET /webhook-deliveries/{id} mit Leserecht.

POST /webhook-deliveries/{id}/retry benötigt alle drei Rechte und JSON {"expectedAttempts":5}, keinen Idempotency-Key. Verwenden Sie den aktuell gelesenen Zähler; ein veralteter liefert 409. Bereits erfolgreich zugestellte Ereignisse werden nicht erneut versendet.

Sandbox und lokale Erfassung

Starten Sie mit einem Sandbox-Empfänger und einem Sandbox-Auftrag. API-Schlüssel des ERP-Workers und erwartete Umgebung müssen ebenfalls Sandbox verwenden.

BetreiberkonfigurationAuswirkung
Webhooks:CaptureOnly = trueStandard: Payload und Signatur werden lokal protokolliert. Kein DNS- oder HTTP-Aufruf, auch nicht an Sandbox-Empfänger.
Webhooks:CaptureOnly = falseEchte HTTP-Zustellung, auch in Development und für Sandbox-Ereignisse.

Kundenseitige Receiver können diese Rebilix-Instanzeinstellung nicht ändern. Bei einer gehosteten Instanz klären Sie sie mit dem Betreiber. Für lokale Entwicklung braucht Ihr Receiver einen öffentlich erreichbaren HTTPS-Zugang zur lokalen Anwendung.

Bereits lokal erfasste Zustellungen werden nach dem Umschalten nicht automatisch versendet. Wählen Sie ausdrücklich „Erneut zustellen“ oder erzeugen Sie einen neuen Auftrag. Mail:CaptureOnly ist eine unabhängige Einstellung für Rechnungs-E-Mails.

Zustellverlauf mit Status Lokal erfasst, zwei Versuchen und dem Link Details
Unter Aufträge & Webhooks → Zustellverlauf zeigt „Details“ die einzelnen Versuche. „Lokal erfasst“ bezeichnet eine Aufzeichnung ohne HTTP-Versand.

Sicherheit und Lebenszyklus

Das Signaturgeheimnis ist kein API-Schlüssel. Der Receiver verwendet es nur zur Prüfung; Dokumente ruft er mit einem getrennten API-Schlüssel mit Leserecht ab. Pro Umgebung und Mandant eigene Konfiguration und erwartete Workspace-ID verwenden.

Für eine neue Zieladresse oder einen neuen Signaturschlüssel den Empfänger deaktivieren und einen Ersatz anlegen. Eine bereits laufende HTTP-Anfrage kann noch enden. Beim Übergang beide Geheimnisse nur so lange wie erforderlich prüfen und die Inbox-Deduplizierung beibehalten.

Die Berechtigung des Erstellers wird vor Zustellungen geprüft. Rollenverlust, Kontosperre oder geänderter Sicherheitsstempel können den Empfänger sperren. Der Rebilix-Betreiber muss Datenbank und Data-Protection-Schlüsselbund dauerhaft sichern und bei mehreren Instanzen teilen.

Konvertierungsbestätigung, Rechnungsausstellung und E-Mail-Versand werden durch Webhooks nicht ausgelöst. Der Beispiel-Receiver aktualisiert ausschließlich einen technischen Status.

Verbindung wird wiederhergestellt …

Neuer Verbindungsversuch in Sekunden.

Die Verbindung konnte nicht wiederhergestellt werden.
Bitte versuchen Sie es erneut oder laden Sie die Seite neu.

Ihre Sitzung wurde pausiert.

Die Sitzung konnte nicht fortgesetzt werden.
Bitte versuchen Sie es erneut oder laden Sie die Seite neu.