Webhooks

Mit Webhooks kann Scrollengine Ihre externen Systeme in Echtzeit benachrichtigen, wenn Ereignisse auftreten. Verwenden Sie Webhooks, um benutzerdefinierte Integrationen zu erstellen, Workflows zu automatisieren oder Daten mit anderen Tools zu synchronisieren.

Was sind Webhooks

Ein Webhook ist eine HTTP-POST-Anfrage, die an eine von Ihnen angegebene URL gesendet wird, wenn ein bestimmtes Ereignis in Scrollengine eintritt. Ihr Server empfängt die Ereignisdaten und kann darauf reagieren.

Verfügbare Webhook-Ereignisse

Ereignis	Auslöser
order.created	Neue Lieferbestellung wurde aufgegeben
order.updated	Bestelldetails oder Status wurden geändert
order.delivered	Bestellung wurde als zugestellt markiert
order.cancelled	Bestellung wurde storniert
route.created	Neue Route wurde erstellt
route.started	Fahrer hat eine Route gestartet
route.completed	Alle Stopps einer Route wurden erledigt
driver.assigned	Fahrer wurde einer Bestellung oder Route zugewiesen

Webhook einrichten

1. Gehen Sie zu Einstellungen > Integrationen > Webhooks
2. Klicken Sie auf Webhook hinzufügen
3. Geben Sie ein:
   • URL — Der Endpunkt auf Ihrem Server, der den Webhook empfangen soll
   • Ereignisse — Wählen Sie die Ereignisse aus, die Sie abonnieren möchten
   • Geheimschlüssel — Ein gemeinsamer Schlüssel zur Überprüfung der Webhook-Authentizität
4. Klicken Sie auf Speichern

Webhook-Payload

Webhooks werden als HTTP-POST-Anfragen mit einem JSON-Body gesendet:

{
  "event": "order.delivered",
  "timestamp": "2026-03-13T14:30:00Z",
  "data": {
    "order_id": "12345",
    "shopify_order_id": "98765",
    "delivery_method": "local_delivery",
    "status": "delivered",
    "driver": {
      "id": "d-001",
      "name": "John Driver"
    }
  }
}

Webhooks verifizieren

Jeder Webhook enthält einen Signatur-Header zur Verifizierung:

1. Scrollengine signiert den Payload mit Ihrem gemeinsamen Geheimschlüssel
2. Die Signatur ist im Header X-Scrollengine-Signature enthalten
3. Ihr Server sollte die Signatur vor der Verarbeitung überprüfen

Wiederholungsrichtlinie

Wenn Ihr Endpunkt einen Nicht-2xx-Statuscode zurückgibt:

• Scrollengine versucht es bis zu 3 Mal erneut
• Wiederholungen verwenden exponentielles Backoff (1 Min., 5 Min., 30 Min.)
• Nach 3 Fehlschlägen wird der Webhook als fehlerhaft markiert
• Sie erhalten eine Benachrichtigung, um Ihren Endpunkt zu reparieren

Anwendungsfälle

• ERP-Synchronisierung — Lieferdaten an Ihr Bestands- oder Buchhaltungssystem senden
• Benutzerdefinierte Benachrichtigungen — SMS-, Slack- oder andere Benachrichtigungen auslösen
• Analysen — Lieferereignisse in Ihre Analyseplattform einspeisen
• Drittanbieter-Logistik — Externe Spediteure oder Partner benachrichtigen