API & Webhooks — Integration, Keys & HMAC-Signatur

shipply lässt sich über eine REST-API und Webhooks in eigene Systeme integrieren — ERP, Warenwirtschaft, eigene Dashboards oder Automatisierungen. Du kannst Bestelldaten abfragen, Produktionsstatuse überwachen und in Echtzeit auf Ereignisse in shipply reagieren, ohne das Portal öffnen zu müssen.

API-Keys

Unter Einstellungen → API kannst du bis zu 10 API-Keys erstellen. Jedem Key gibst du einen beschreibenden Namen, zum Beispiel ERP-Anbindung oder Reporting-Tool. So siehst du auf einen Blick welches System welchen Key nutzt.

Ein Key wird nur einmal vollständig angezeigt — direkt nach der Erstellung. Notiere ihn sofort an einem sicheren Ort. Danach ist aus Sicherheitsgründen nur noch der Anfang sichtbar. Verwende den Key in deiner Anwendung im Authorization-Header.

Webhooks

Webhooks schicken eine Benachrichtigung an eine HTTPS-URL deiner Wahl sobald etwas in shipply passiert. Du kannst bis zu 10 Endpunkte konfigurieren.

Ereignisse die du abonnieren kannst umfassen unter anderem: Bestellung eingegangen, bezahlt, in Produktion, versendet, Zahlung fehlgeschlagen, Rechnung erstellt. Du kannst einzelne Events auswählen oder alle abonnieren.

Jeder Zustellversuch wird mit Zeitstempel protokolliert. Du siehst im Portal ob die Zustellung erfolgreich war oder fehlgeschlagen ist — und kannst Events manuell erneut zustellen lassen, ohne Programmieraufwand.

HMAC-SHA256-Signaturprüfung

Jeder Webhook-Request enthält im Header eine Signatur die sicherstellt dass die Nachricht wirklich von shipply stammt. Das Signing-Secret ist ebenfalls nur beim Anlegen des Endpunkts einmalig sichtbar — danach nicht mehr abrufbar.

So prüfst du die Signatur in deinem Server: berechne den HMAC-SHA256 des rohen Request-Body (nicht des geparsten Objekts) mit dem Signing-Secret und vergleiche das Ergebnis mit dem Wert im Header. Stimmen sie überein, ist die Nachricht authentisch.

Wichtig: prüfe den rohen Body-String, nicht das geparste JSON. Wenn dein Server den Body erst parsed und dann neu serialisiert, weicht die Signatur ab.

So funktioniert's

1. API-Key anlegen — gehe zu Einstellungen → API → Neuer Key. Vergib einen Namen der das verwendende System beschreibt. Notiere den angezeigten Key sofort.
2. Endpunkt anlegen — unter Einstellungen → Webhooks → Neuer Endpunkt trägst du deine HTTPS-URL ein und wählst welche Events dein Server empfangen soll.
3. HMAC-Signatur verifizieren — implementiere die Signaturprüfung in deinem Server wie oben beschrieben. Ohne Prüfung akzeptierst du theoretisch auch gefälschte Requests.
4. Zustellung überwachen — im Portal siehst du für jeden Endpunkt das Zustellprotokoll. Fehlgeschlagene Events kannst du manuell erneut auslösen. Prüfe nach dem ersten echten Test ob der Event ankam und korrekt verarbeitet wurde.

Bei Fragen zur Integration steht der shipply-Support unter Kontakt zur Verfügung.

Mögliche Fehler & Ursachen

Ich habe meinen API-Key nicht notiert und er ist jetzt nicht mehr sichtbar.

Ein API-Key wird in shipply nur beim ersten Erstellen vollständig angezeigt. Danach ist aus Sicherheitsgründen nur noch der Anfang sichtbar. Lösche den alten Key und erstelle einen neuen. Stelle in deiner Anwendung den neuen Key ein und teste die Verbindung.

Webhook-Events kommen nicht an meinem Server an.

Prüfe zuerst ob dein Endpunkt öffentlich erreichbar ist — localhost-Adressen funktionieren nicht. shipply benötigt eine HTTPS-URL mit gültigem Zertifikat. Prüfe außerdem ob eine Firewall oder ein Reverse-Proxy die Requests blockiert. Im Portal unter Webhooks → Zustellprotokoll siehst du ob shipply die Zustellung versucht hat und welchen Fehler dein Server zurückgegeben hat.

Die Signaturprüfung schlägt fehl, obwohl das Signing-Secret stimmt.

Häufige Ursache: dein Server verändert den Request-Body vor der Signaturprüfung — zum Beispiel durch JSON-Parsing und erneutes Serialisieren. Die Signatur wird über den rohen Body berechnet. Prüfe den rohen Body-String, nicht das geparste Objekt. Ein weiterer Auslöser kann ein Encoding-Unterschied sein (UTF-8 vs. andere Codierung).

Ich habe das Limit von 10 API-Keys oder 10 Webhooks erreicht.

Lösche nicht mehr benötigte Keys oder Endpunkte. Überlege ob du mehrere Systeme über einen gemeinsamen Key bedienen kannst, wenn sie dieselben Berechtigungen benötigen. Wenn dein Use Case mehr als 10 Keys oder Webhooks erfordert, wende dich an den shipply-Support über Kontakt.

Ein Event wurde laut Protokoll zugestellt, kam aber doppelt bei uns an.

Das kann bei Netzwerk-Timeouts passieren: shipply sieht keine Bestätigung und versucht die Zustellung erneut, obwohl dein Server das Event schon verarbeitet hat. Baue Idempotenz in deine Verarbeitung ein — prüfe anhand der Event-ID ob du ein Event bereits verarbeitet hast, bevor du es erneut verarbeitest. Die Event-ID ist in jedem Webhook-Payload enthalten.