Sendungsstatus-Webhooks

Was du mit Webhooks automatisieren kannst

Mit einem Webhook verbindest du PAQATO mit deinen eigenen Systemen: Sobald sich der Status einer Sendung ändert, schickt PAQATO die Information sofort an eine URL deiner Wahl – ohne dass du manuell nachschauen oder Daten exportieren musst.

Typische Anwendungsfälle:

Support entlasten: Bei „Zustellung nicht möglich" oder „Verzögert" automatisch ein Ticket in deinem Support-Tool anlegen oder einen internen Slack-Kanal informieren – bevor sich der Kunde meldet.
Warenwirtschaft synchron halten: Retouren automatisch in dein ERP-/Lagersystem einbuchen, sobald sie unterwegs sind.
Kundenkommunikation ergänzen: Bei „Zugestellt" automatisiert eine Bewertungsanfrage verschicken, oder bei „Abholbereit" eine zusätzliche Erinnerung senden.
Eigene Auswertungen füttern: Sendungsereignisse in Echtzeit in dein eigenes Dashboard oder Data Warehouse übernehmen.

Aktuell steht ein Webhook-Typ zur Verfügung: der Sendungsstatus-Webhook, der bei Statusänderungen einer Sendung ausgelöst wird. Welche Statusänderungen genau, bestimmst du selbst (siehe Schritt 4 unten).

Webhook einrichten

Du richtest Webhooks jetzt selbstständig über den Integrations-Assistenten ein – eine manuelle Freischaltung durch den PAQATO Customer Success ist nicht mehr nötig. Du kannst mehrere Webhooks parallel anlegen, z. B. einen für alle Ereignisse an dein Lagersystem und einen weiteren nur für verzögerte Zustellungen an einen Slack-Kanal.

Gehe in der PAQATO App zu Einstellungen → Datenanbindung → Integrationen.
Wechsle auf den Tab Verfügbare Integrationen und wähle die Kachel Webhook.
- Ist die Funktion in deinem Vertrag noch nicht enthalten, kannst du sie über den Button „Anfragen" anfragen.
Klicke auf Integration starten, um den Assistenten zu öffnen, und fülle die folgenden vier Schritte aus.

Schritt 1 – Allgemein

Feld	Beschreibung
Name	Frei wählbarer Name, um diesen Webhook später in deiner Integrationsliste wiederzuerkennen, z. B. "Lagerverwaltung" oder „Zustellprobleme an Slack".
Webhook-URL	Adresse deines Systems, an die PAQATO jedes Ereignis als HTTP-POST-Anfrage sendet, z. B. `ttps://mein-shop.de/api/paqato-webhook`. Du bekommst sie vom System, das die Daten empfangen soll.

Schritt 2 – Sicherheit: Basic Auth (optional)

Nur ausfüllen, wenn dein Empfänger-System per HTTP Basic Auth geschützt ist. Das sind nicht deine
PAQATO-Zugangsdaten, sondern die Zugangsdaten, die dein Empfänger-System erwartet.

Benutzername (des Empfänger-Systems)
Passwort (des Empfänger-Systems) – beim späteren Bearbeiten leer lassen, um das gespeicherte Passwort zu behalten.

Im Zweifel leer lassen und deine interne IT fragen.

Schritt 3 – Sicherheit: HTTP-Header & Signatur (optional)

Eigene HTTP-Header: Nur nötig, wenn dein Empfänger-System zusätzliche HTTP-Header erwartet (z. B. einen API-Key). PAQATO sendet jeden hier eingetragenen Header bei jeder Anfrage mit.
Signatur-Schlüssel (HMAC-SHA256): Wird automatisch pro Account erzeugt und hier nur angezeigt – du musst ihn nicht selbst eintragen. PAQATO signiert damit jeden gesendeten Webhook (Feld security im Payload, siehe unten). Deine IT hinterlegt ihn im Empfänger-System, um zu prüfen, dass Anfragen wirklich von PAQATO stammen. Der Schlüssel gilt für alle Webhooks deines Accounts.

Auch dieser Schritt ist optional – im Zweifel leer lassen und deine interne IT fragen.

Schritt 4 – Shops, Ereignisse & Aktivierung

Hier legst du fest, wodurch der Webhook ausgelöst wird – je genauer du filterst, desto gezielter kannst du damit arbeiten.

Feld	Beschreibung
Nur Retouren	Angehakt löst der Webhook nur bei Retouren aus, nicht angehakt bei allen Sendungen. Praktisch, wenn du Retouren separat verarbeiten willst, z. B. für dein Warenwirtschaftssystem.
Ereignisse	Sendungsereignisse, bei denen der Webhook ausgelöst werden soll. Ohne Auswahl werden alle Ereignisse gesendet – wähle gezielt aus, wenn du z. B. nur bei Problemen benachrichtigt werden willst.
Shops	Optional – löst den Webhook nur für Sendungen der ausgewählten Shops aus. Ohne Auswahl gilt er für alle deine Shops. Hilfreich, wenn du mehrere Marken/Shops in einem Account verwaltest, aber nur für einen automatisiert reagieren möchtest.
Aktiv	Haken entfernen, um den Webhook vorübergehend zu pausieren, ohne ihn zu löschen – z. B. während Wartungsarbeiten an deinem System. Jederzeit wieder aktivierbar.

Die auswählbaren Ereignisse sind nach Anwendungsfall gruppiert:

Gruppe	Beispiel-Anwendungsfall
Vor Versand	Eigene Vorbereitung anstoßen, bevor das Paket das Lager verlässt
Unterwegs	Laufende Sendungen in eigenen Systemen nachverfolgen
Zugestellt	Bewertungsanfrage oder Dankes-Mail automatisch verschicken
Abholbereit	Zusätzliche Erinnerung an die Kundschaft senden
Zustellung verzögert	Support proaktiv informieren, bevor sich Kund:innen melden
Zustellung nicht möglich	Support-Ticket automatisch anlegen
Retoure	Lagerbestand/Warenwirtschaft aktualisieren
Weitere Ereignisse	Sonstige, seltenere Statusänderungen

Klicke abschließend auf Fertig, um den Webhook zu speichern.

Für deine IT: technische Details

Die folgenden Abschnitte richten sich an die Person, die den Empfänger-Endpunkt bei dir baut oder betreut.

Payload-Struktur

Jede Webhook-Anfrage ist ein HTTP-POST mit folgendem JSON-Aufbau:

{
  "security": {
    "timestamp": "[Unix-Zeitstempel]",
    "token": "[UUID]",
    "signature": "[HMAC-SHA256-Hash]"
  },
  "data": {}
}

Das Feld data enthält die Details des ausgelösten Ereignisses, u. a. die ID des Sendungsstatus als eventId.

Signatur prüfen

So stellt eure Empfänger-Anwendung sicher, dass eine Anfrage wirklich von PAQATO stammt:

timestamp und token aus dem security-Objekt verketten.
Daraus einen HMAC-SHA256-Hash mit dem Signatur-Schlüssel bilden (sichtbar in Schritt 3 des Assistenten).
Das Ergebnis mit dem Feld signature vergleichen. Stimmen die Werte überein, stammt die Anfrage von PAQATO.

Antwortverhalten & Wiederholungen

Der Endpunkt sollte bei erfolgreichem Empfang mit HTTP-Status 200 antworten. Bei jedem anderen Status-Code wiederholt PAQATO die Zustellung:

Erster Versuch + 5 Wiederholungen nach 10 Minuten, 30 Minuten, 1 Stunde, 2 Stunden und 4 Stunden. Schlagen alle Versuche fehl, wird die Nachricht verworfen.

Verfügbare Webhook-Typen

Sendungsstatus-Webhook: Löst bei einer Statusänderung einer Sendung aus, eingeschränkt durch die von dir gewählten Ereignisse, Shops und den Retouren-Filter.