Express Kurier. Direkt.
Auch Overnight.
x25pronto Schweiz bringt Ware direkt ans Ziel. Für kleine Ware fährt ein Auto. Für mehr Platz gibt es Transporter oder XL. Direkt, Express und Overnight fahren von Montag bis Sonntag. Freie Zeiten stehen im Kalender.
Webhook-Implementierung: Leitfaden für Schweizer ERP-Anbindungen
Konkrete Schritte zur Implementierung von Webhooks zwischen Ihrem Schweizer ERP und einem Kurierdienst. Technische Anforderungen, Sicherheitsmassnahmen und Beispiel-Payloads.
Kurzantwort
Dieser Leitfaden zeigt, wie Sie Webhooks sicher und zuverlässig zwischen Ihrem Schweizer ERP und einem Kurierdienst integrieren. Er behandelt Endpoint-Design, Authentifizierung (HMAC/Token), Beispiel-Payloads, Zustell- und Retry-Strategien sowie Logging und Monitoring.
Warum Webhooks statt Polling?
Webhooks senden Ereignisse direkt vom Kurierdienst an Ihr ERP. Sie sparen API-Aufrufe und erreichen schnellere Reaktionszeiten. Für Sendungsstatus, Abholanforderungen oder Lieferbestätigungen sind Webhooks oft effizienter als regelmässiges Abfragen.
Grundanforderungen für den Endpoint
Ihr ERP oder ein zwischengeschalteter Integrationsdienst braucht eine öffentlich erreichbare HTTPS-URL mit gültigem TLS-Zertifikat. Die Endpoint-URL sollte nur POST-Anfragen akzeptieren. Setzen Sie Zeitlimits (z.B. 5–10 Sekunden) und begrenzen Sie Payload-Grössen. Akzeptieren Sie JSON als Standard-Format.
Authentifizierung und Sicherheit
Nutzen Sie HMAC-Signaturen (z.B. HMAC-SHA256) über einen gemeinsamen Secret für Integrität und Authentizität. Alternativ sind kurzlebige Bearer-Tokens möglich. Verifizieren Sie Kopfzeilen wie X-Signature, X-Request-Id und prüfen Sie Timestamp, um Replay-Attacken zu verhindern. Verbindungsverschlüsselung (TLS 1.2/1.3) ist Pflicht. Beschränken Sie die IP-Adressen, falls der Kurierdienst stabile IPs bereitstellt.
Beispiel-Payloads
Standardisiere Felder, damit Ihr ERP die Daten zuverlässig verarbeitet. Beispiel: Sendungsstatus-Event: { "event": "shipment.updated", "id": "KD-12345", "status": "delivered", "timestamp": "2024-10-02T09:30:00Z", "metadata": { "orderId": "ORD-9876", "customerRef": "CH-001" } } Für Abholanforderungen senden Sie Adresse, Zeitfenster und Packhinweis. Verwenden Sie konsistente Datentypen (ISO-8601 für Zeiten, Strings für IDs).
Zustell- und Retry-Strategien
Der Kurierdienst versucht, den Webhook zuzustellen. Implementieren Sie idempotente Verarbeitung anhand einer eindeutigen requestId. Akzeptieren Sie kurzzeitige Fehler (5xx) mit Backoff-Retry auf Senderseite. Für Ihre ERP-Seite sollte ein 2xx-Statuscode die erfolgreiche Verarbeitung signalisieren. Bei zeitweiligen Ausfällen nutzen Sie ein Dead-Letter-Queue- oder Wiederholungs-Log, um Daten nicht zu verlieren.
Fehlerbehandlung, Logging und Monitoring
Loggen Sie Eingang, Signaturprüfung und Verarbeitungsresultat. Erstellen Sie Dashboards für Fehlerraten und Latenz. Alarmieren Sie bei wiederholten Fehlzuständen. Stellen Sie einen Health-Endpoint bereit, damit der Kurierdienst prüfen kann, ob Ihr Endpoint erreichbar ist.
Häufige Fragen
Wie prüfe ich eine HMAC-Signatur?
Berechnen Sie HMAC-SHA256 über den Raw-Body mit dem geteilten Secret und vergleichen Sie das Ergebnis konstantzeit-sicher mit dem Header X-Signature. Prüfen Sie zusätzlich den Timestamp im Header, um Replay-Attacken zu vermeiden.
Was mache ich bei mehrfacher Zustellung desselben Events?
Verarbeiten Sie Webhooks idempotent. Speichern Sie eine requestId oder eventId und ignorieren Sie wiederholte Events, wenn die ID bereits bearbeitet wurde. So vermeiden Sie doppelte Buchungen oder weitere Schadenfälle.
Welche Rolle spielt TLS und welche Versionen sind empfohlen?
TLS sichert die Verbindung. Verwenden Sie TLS 1.2 oder 1.3. Verwerfen Sie veraltete Cipher-Suites und prüfen Sie Zertifikate regelmässig auf Ablauf.
Wie teste ich die Integration lokal?
Nutzen Sie ein temporäres Tunneling-Tool (z.B. ngrok) oder einen Integrations-Endpoint in einer Staging-Umgebung. Simulieren Sie Signaturen und verschiedene Response-Codes, um Retry- und Fehlerpfade zu prüfen.