Statusupdates, Retries und Webhooks

Die Partner API stellt den aktuellen Lieferstatus sowohl per Abruf als auch über signierte Webhooks bereit.

Status abrufen#

• GET /partner/v1/deliveries/{id} liefert die vollständige Lieferungsressource.
• GET /partner/v1/deliveries/{id}/tracking liefert Status, ETA, verbleibende Distanz, Routen-Polyline sowie die verfügbare Kurierposition.
• GET /partner/v1/deliveries listet Lieferungen mit Cursor-Paginierung über page_token.

Unterstützte Status sind pending, courier_assigned, at_pickup, picked_up, in_transit, at_dropoff, delivered, cancelled und expired.

Abrufe bleiben der verlässliche Weg für initiales Laden, Reconnects und den Abgleich nach einem verpassten Event. Webhooks dienen als unmittelbare Benachrichtigung.

Webhooks verwenden#

Registrieren Sie einen HTTPS-Endpoint über POST /partner/v1/webhooks. Sie können alle oder ausgewählte Events abonnieren:

• delivery.created
• delivery.status_updated
• delivery.courier_assigned
• delivery.courier_arrived
• delivery.eta_updated
• delivery.pod_submitted
• delivery.delivered
• delivery.cancelled

Das Signing Secret whsec_… wird nur beim Anlegen oder Rotieren zurückgegeben. Verifizieren Sie x-signature über Event-ID, Delivery-ID, Zeitstempel und den SHA-256-Hash des unveränderten Request-Bodys. Prüfen Sie außerdem x-event-timestamp gegen ein kurzes Zeitfenster.

Zustellung und Retries#

• Webhooks werden mindestens einmal zugestellt. Deduplizieren Sie anhand von x-event-id beziehungsweise der Event-ID im Body.
• Netzwerkfehler, 408, 409, 425, 429 und 5xx werden mit exponentiellem Backoff und Jitter wiederholt.
• Nach acht fehlgeschlagenen Versuchen landet die Zustellung in der Dead-Letter Queue.
• Mit POST /partner/v1/webhooks/{id}/replay können fehlgeschlagene Zustellungen erneut eingereiht werden.
• Ihr Endpoint sollte eine erfolgreiche Zustellung schnell mit einem 2xx-Status bestätigen und längere Verarbeitung asynchron ausführen.

Behandeln Sie Webhooks als Signal und gleichen Sie den aktuellen Zustand bei Unsicherheit erneut über die Delivery- oder Tracking-Ressource ab.