Webhooks integrieren
Signierte Benachrichtigungen sicher in Ihr ERP oder Ihre Anwendung integrieren.
Auf dieser Seite
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.
In fünf Schritten zur Integration
- Stellen Sie einen öffentlich erreichbaren Receiver bereit, zum Beispiel
https://erp.example.com/webhooks/rebilix. - Ö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.
- Speichern Sie das einmal angezeigte
whsec_…-Geheimnis im Secret Store des Receivers. - Starten Sie einen Hintergrundauftrag und speichern Sie dessen Job-ID bei Ihrem ERP-Datensatz.
- 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
| Anforderung | Verhalten |
|---|---|
| HTTPS · Port 443 | Öffentlicher DNS-Hostname und gültiges TLS-Zertifikat. Keine IP-Literale, Zugangsdaten, Query-Parameter oder URL-Fragmente. |
| POST · application/json | Originalbytes bis höchstens 64 KiB lesen; vor der Signaturprüfung nicht deserialisieren oder neu formatieren. |
| Direkte Antwort | Keine Login-Seite und keine Weiterleitung. Die Signatur authentifiziert die Anfrage, nicht eine ERP-Browsersitzung. |
| Schnell bestätigen | Nach Datenbank-Commit mit 2xx antworten. Rebilix wartet höchstens 15 Sekunden auf die HTTP-Antwort. |
| Öffentlich erreichbar | Private / 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.
{
"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
}| Feld | Bedeutung |
|---|---|
| id | Ereignis-UUID. Bleibt bei Zustellwiederholungen gleich. |
| type / state | job.succeeded / succeeded oder job.failed / failed. |
| environment | sandbox oder live; muss zur Receiver-Konfiguration passen. |
| createdAt | Zeitpunkt des terminalen Ereignisses, nicht des aktuellen Zustellversuchs. |
| version | Payload-Schema, aktuell 1. Änderungen bewusst behandeln. |
| workspaceId | Arbeitsbereich des Auftrags. Mit dem erwarteten Mandanten vergleichen. |
| jobId / operation | Auftrag und Aktion: generate, parse, validate oder conversion-review. |
| resultStatus | valid, invalid, not_checked, ready oder blocked; bei Verarbeitungsfehlern null. |
| documentId | Referenz auf gespeichertes Dokument; andernfalls null. |
| conversionReviewId | Referenz auf Konvertierungsprüfung; andernfalls null. |
| errorCode | Technischer Fehlercode bei job.failed; bei Erfolg null. |
Auch resultStatus: invalid oder blocked kann zu einem abgeschlossenen Auftrag gehören. Das Ereignis enthält keine Rechnungsdateien, Kundendaten oder API-Schlüssel.
{
"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
| Header | Zweck |
|---|---|
| X-Rebilix-Event-Id | Stabile Ereignis-ID; nach Prüfung mit payload.id vergleichen. |
| X-Rebilix-Delivery-Id | Zustellung für dieses Ereignis / diesen Empfänger. Nur zur Korrelation; nicht als Deduplizierungsschlüssel verwenden. |
| X-Rebilix-Timestamp | Unix-Sekunden, für jeden Versuch neu gesetzt. |
| X-Rebilix-Signature | v1= 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.
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
- Signatur falsch / Zeitfenster abgelaufen: mit 401 ablehnen, keine ERP-Daten ändern.
- Gültiges neues Ereignis: Originalpayload und Ereignis-ID in einer persistenten Inbox speichern. Ein eindeutiger Datenbankindex verhindert parallele Duplikate.
- Identisches bereits gespeichertes Ereignis: erneut 2xx zurückgeben, keine zweite Geschäftsaktion ausführen.
- Datenbank-Commit fehlgeschlagen: keinen Erfolg bestätigen. Eine 5xx-Antwort ermöglicht Rebilix die Wiederholung.
- 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.
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 / Situation | Rebilix-Verhalten |
|---|---|
| 2xx | Als zugestellt markieren. |
| Netzwerkfehler, 408, 429, 5xx | Automatisch wiederholen: 30 / 60 / 120 / 240 Sekunden. Retry-After kann die Wartezeit bis zu einer Stunde verlängern. |
| Andere HTTP-Statuscodes | Automatische Wiederholung stoppen. Nach Fehlerbehebung gegebenenfalls ausdrücklich erneut zustellen. |
| Verbindungsabbruch nach Empfang | Ergebnis 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.
| Betreiberkonfiguration | Auswirkung |
|---|---|
| Webhooks:CaptureOnly = true | Standard: Payload und Signatur werden lokal protokolliert. Kein DNS- oder HTTP-Aufruf, auch nicht an Sandbox-Empfänger. |
| Webhooks:CaptureOnly = false | Echte 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.

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.