Webhooks

Webhooks ermöglichen es einem externen System, Echtzeit-Benachrichtigungen zu empfangen, wenn in ProcureSwift ein Ereignis eintritt – zum Beispiel wenn eine Bestellung erstellt wird, sich der Status einer Rechnung ändert oder ein Angebot eingeht. Anstatt die API regelmäßig abzufragen, registriert das externe System eine URL, und ProcureSwift sendet bei jedem abonnierten Ereignis eine JSON-Nutzlast an diese URL.

Wo Sie es finden

Öffnen Sie im Hauptmenü Webhooks (/webhooks). Die Seite erfordert die Berechtigung Webhooks / View.

Verfügbare Ereignisse

Ein Abonnement kann auf eines oder mehrere der folgenden Ereignisse lauschen:

• purchase_order.created
• purchase_order.status_changed
• invoice.created
• invoice.status_changed
• rfq.published
• rfp.published
• delivery_note.created
• quotation.received
• proposal.received

Webhook-Abonnement erstellen

1. Klicken Sie auf Webhook hinzufügen.
2. Füllen Sie das Formular aus:
   • Webhook-URL — ein öffentlich erreichbarer HTTPS-Endpunkt, der die Ereignis-Nutzlasten empfängt. Pflichtfeld.
   • Ereignisse — wählen Sie mindestens ein Ereignis aus, das abonniert werden soll. Der Webhook wird nur für die ausgewählten Ereignisse ausgelöst.
3. Klicken Sie auf Erstellen.

Einmalige Anzeige des Secrets

Unmittelbar nach der Erstellung wird das Signing Secret des Webhooks einmalig in einem Bestätigungsdialog angezeigt. Kopieren Sie es sofort und speichern Sie es sicher auf dem empfangenden System — die Plattform zeigt es nie wieder an. Das Secret wird benötigt, um eingehende Anfragen als tatsächlich von ProcureSwift stammend zu verifizieren (siehe Signaturverifizierung weiter unten).

Abonnements verwalten

Die Tabelle Abonnements auf /webhooks zeigt: URL, Ereignisse, Status, Zuletzt ausgelöst, aufeinanderfolgende Fehler (Serie) sowie das Erstellungsdatum.

Aktionen pro Zeile:

• Status-Schalter — schalten Sie den Schalter um, um ein Abonnement zu aktivieren oder zu deaktivieren, ohne es zu löschen. Deaktivierte Webhooks empfangen keine Ereignisse mehr, ihre Konfiguration bleibt jedoch erhalten.
• Bearbeiten (Stift-Symbol) — URL oder Liste der abonnierten Ereignisse ändern.
• Löschen (Papierkorb-Symbol) — das Abonnement dauerhaft entfernen.

Die Spalte Fehler (Serie) zählt aufeinanderfolgende fehlgeschlagene Zustellversuche. Ein Wert größer als null bedeutet, dass der empfangende Endpunkt Anfragen ablehnt oder nicht erreichbar ist. Bei einer langen Fehlerserie kann die Plattform den Webhook automatisch drosseln oder deaktivieren.

Signaturverifizierung (HMAC)

Jede Webhook-Anfrage enthält einen Signatur-Header, der aus dem Anfrage-Body und dem Signing Secret des Abonnements berechnet wird. Das empfangende System muss diese Signatur vor der Verarbeitung der Nutzlast überprüfen — andernfalls könnte jeder, der die URL kennt, gefälschte Ereignisse einsenden.

Der grundlegende Verifizierungsablauf auf der Empfängerseite:

1. Den rohen Anfrage-Body lesen.
2. HMAC-SHA256(secret, body) berechnen.
3. Das Ergebnis in konstanter Zeit mit dem Signatur-Header der Anfrage vergleichen.
4. Die Anfrage ablehnen, wenn die Werte nicht übereinstimmen.

Speichern Sie das Secret in der Umgebungskonfiguration des Empfängers — niemals in der Versionskontrolle.

Wiederholungsversuche

Gibt der empfangende Endpunkt einen Nicht-2xx-Statuscode zurück oder kommt es zu einem Timeout, wiederholt die Plattform die Zustellung nach einem Backoff-Zeitplan. Die Spalte Zuletzt ausgelöst zeigt den letzten Versuch (erfolgreich oder nicht), und Fehler (Serie) gibt an, wie viele aufeinanderfolgende Versuche seit dem letzten Erfolg fehlgeschlagen sind. Eine erfolgreiche Zustellung setzt den Fehlerzähler auf null zurück.

Secret rotieren

Das Signing Secret wird bei der Erstellung des Webhooks generiert und einmalig angezeigt. Um es zu rotieren, löschen Sie das Abonnement und erstellen ein neues (wodurch ein neues Secret erzeugt wird), und aktualisieren Sie anschließend das Secret auf dem empfangenden System. Koordinieren Sie die Umstellung so, dass das empfangende System dem neuen Secret vertraut, bevor das alte Abonnement entfernt wird.

Tipps

• Verwenden Sie Bearbeiten, um neue Ereignistypen zu einem bestehenden Abonnement hinzuzufügen, anstatt für jedes Ereignis einen separaten Webhook zu erstellen.
• Machen Sie den Empfänger idempotent — die Plattform kann Wiederholungsversuche durchführen, sodass dasselbe Ereignis mehr als einmal eintreffen kann. Verwenden Sie die Ereignis-ID in der Nutzlast zur Deduplizierung.
• Antworten Sie mit 200 OK, sobald die Nutzlast gespeichert wurde, und verarbeiten Sie sie asynchron. Langläufige Handler können Wiederholungsversuche auslösen.
• Überwachen Sie die Spalte Fehler (Serie) oder richten Sie einen Alarm ein, wenn der Wert größer als null wird.

Berechtigungen

Aktion	Erforderliche Berechtigung
Abonnements anzeigen	Webhooks / View
Webhook hinzufügen	Webhooks / Create
Webhook bearbeiten, aktivieren/deaktivieren	Webhooks / Update
Webhook löschen	Webhooks / Delete

Verwandte Anleitungen

• API-Schlüssel und Audit-Logs — für ausgehende API-Aufrufe aus Ihren Systemen an ProcureSwift.