WEBHOOKS
Webhooks
Erhalten Sie Echtzeitereignisse von Superroute — Bestellungen, Statusänderungen, Tracking-Updates. Mit signierten Payloads, automatischen Wiederholungen und integriertem Debugger.
WEBHOOKS
Erhalten Sie Echtzeitereignisse von Superroute — Bestellungen, Statusänderungen, Tracking-Updates. Mit signierten Payloads, automatischen Wiederholungen und integriertem Debugger.
Ein Webhook ist eine HTTP-POST-Anfrage, die Superroute an eine von Ihnen konfigurierte URL sendet, sobald ein Ereignis eintritt — eine Bestellung wird erstellt, eine Lieferung abgeschlossen, ein Tracking-Ereignis erfasst. Sie erstellen einen Empfangsendpunkt, wir liefern das Ereignis dorthin.
Ereignisse werden in eine Warteschlange eingereiht und asynchron gesendet. Jede Anfrage trägt eine HMAC-SHA256-Signatur, mit der Sie die Herkunft prüfen können. Fehlgeschlagene Zustellungen (nicht 2xx oder Timeout) werden mit exponentiellem Backoff bis zu 5-mal wiederholt.
Sie konfigurieren ein gemeinsames Geheimnis auf der Einstellungsseite. Jeder ausgehende Webhook wird damit signiert. Ihr Empfänger berechnet die Signatur neu und vergleicht — bei Übereinstimmung ist die Payload echt und unverändert.
Acht ausgehende Ereignistypen sind verfügbar. Jeder hat ein eigenes URL-Feld auf der Einstellungsseite — abonnieren Sie eine beliebige Teilmenge.
Maschinenlesbare Beschreibung aller ausgehenden Ereignisse mit Payload-Schemas, Headern und Wiederholungsplänen (AsyncAPI 3.0): asyncapi-webhooks.json
Wird ausgelöst, sobald eine lokale Lieferbestellung (Delivery / Pickup / P2P) angelegt wird — über beliebigen Weg: Webformular, REST/GraphQL-API, E-Commerce-Plattform-Synchronisation, automatische Regeln, Importzeilen usw. Label-Service- und andere Nicht-Lieferarten sind ausgeschlossen. Wird im Batch-Flow übersprungen, wenn für denselben Empfänger auch order_create_async_postback_url konfiguriert ist. Konfigurieren Sie mit order_create_webhook_url.
Payload-BeispieleWird bei jedem Statuswechsel ausgelöst — abgeholt, unterwegs, zugestellt, Ausnahme, storniert. Konfigurieren Sie mit order_status_change_webhook_url.
Payload-BeispieleWird bei jedem Tracking-Lebenszyklusereignis ausgelöst (Daten übermittelt, Zustellung gestartet, erfolgreich zugestellt usw.). Konfigurieren Sie mit tracking_event_webhook_url. Zustell- und Abholereignisse enthalten außerdem den Zustellnachweis: proof_files sowie proof_files_detail (file_id, type, url, full_url, signierte Download-URL). Nach dem Ereignis hochgeladene Fotos kommen als pod.files_updated. Jede Datei trägt zusätzlich ihren Ereigniskontext: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) und service_status (1 = success / 2 = failed); bei Altdateien ohne erfasstes Ereignis sind sie null.
Payload-BeispieleWird einmal ausgelöst, nachdem ein Stapelimport abgeschlossen ist. Payload enthält die Ergebnisse pro Zeile. Konfigurieren Sie mit order_create_async_postback_url.
Payload-BeispieleWird ausgelöst, wenn ein Zustellfoto oder eine Unterschrift hinzugefügt, ersetzt oder entfernt wird (action: added / updated / removed) — eine Zustellung pro Datei, kein Abfragen von Anhängen mehr. Aktivierung über pod_files_webhook_url. Jede Datei trägt zusätzlich ihren Ereigniskontext: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) und service_status (1 = success / 2 = failed); bei Altdateien ohne erfasstes Ereignis sind sie null. Ersetzt ein Mitarbeiter ein Foto oder eine Unterschrift oder legt eine archivierte Version als aktuell fest, wird die Datei mit action: updated gesendet und enthält nur das aktuelle Bild; archivierte Versionen werden nie gesendet.
Payload-BeispieleWird ausgelöst, wenn eine Bestellung endgültig gelöscht wird, damit Ihr System die Entfernung nachvollziehen kann. Aktivierung über order_deleted_webhook_url.
Payload-BeispieleWird ausgelöst, wenn ein Stornierungsversuch abgelehnt wird (z. B. weil die Bestellung bereits in Zustellung ist), damit Ihre Betriebsprozesse fehlgeschlagene Stornierungen ohne API-Abfragen überwachen können. Aktivierung über order_cancel_failed_webhook_url.
Payload-BeispieleWird ausgelöst, wenn ein Platz auf dem Routen-Board den Besitzer wechselt oder das Board seinen Status ändert — das Feld action sagt, was passiert ist (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Nur auf Unternehmensebene. Opt-in über route_board_webhook_url.
Payload-BeispieleEin eigener Webhook-Kanal für Drittanbieter-ZustellAnbieter mit Smart-Locker-Anbindung. Ereignisse werden an den für Ihr Anbieterkonto konfigurierten Endpunkt zugestellt; jeder Endpunkt kann eine beliebige Teilmenge der Ereignistypen abonnieren.
Türen Geöffnet — Wird ausgelöst, sobald sich die Fachtüren für einen Zustellversuch öffnen — egal ob der Kurier den Zugangscode am Bildschirm des Schließfachs eingegeben oder die Fernöffnungs-API genutzt hat — einschließlich erneuter Öffnungen nach Fachwechsel. Der opening-Block listet jedes geöffnete Fach mit grid_id, Hardware-Fachnummer compartment_number und pickup_locker_number (fortlaufende Anzeigenummer, spaltenweise von oben nach unten, dann von links nach rechts). Jedes Fach führt zusätzlich pickup_locker_code — die Bezeichnung "{shelf_code}-{pickup_locker_number}", zu der der Empfänger geschickt wird; null, wenn das Fach keine Abholnummer hat. Die Nutzlast enthält außerdem pickup_code — den Abholcode des Empfängers, der im Moment des Türöffnens vergeben wird; er bleibt nach der Einlegebestätigung des Kuriers derselbe Code und kann erst nach dieser Bestätigung zur Abholung verwendet werden.
Payload-BeispieleIn Paketfach zugestellt — Wird ausgelöst, wenn eine Einlagerung bestätigt wurde und die Pakete im Schließfach liegen. Die Nutzlast enthält den Abholcode des Empfängers. Jedes Fach führt zusätzlich pickup_locker_code — die Bezeichnung "{shelf_code}-{pickup_locker_number}", zu der der Empfänger geschickt wird; null, wenn das Fach keine Abholnummer hat. Bei über die Fernöffnungs-API geöffneten Türen schließt die Plattform die Einlagerung selbst ab, sobald der Schrank alle geöffneten Türen als geschlossen meldet; das Ereignis wird dann ohne confirm-Aufruf ausgelöst. confirmed_by nennt den Abschlussweg: courier_terminal, partner_api, door_close, timeout_door_closed oder console.
Payload-BeispieleAbgeholt — Wird ausgelöst, wenn der Empfänger die eingelagerten Pakete abgeholt hat.
Payload-BeispieleZustellung fehlgeschlagen — Wird ausgelöst, wenn eine Zustellung fehlschlägt; Fehlercodes pro Paket sind enthalten.
Payload-BeispieleAbgelaufen — Wird ausgelöst, wenn ein ungenutzter Zustellcode oder eine nicht abgeholte Einlagerung die Ablaufzeit überschreitet.
Payload-BeispieleStorniert — Wird ausgelöst, wenn eine Zustellung vor Abschluss storniert wird.
Payload-BeispieleKorrektur-Öffnung — Wird ausgelöst, wenn die belegten Fächer innerhalb des Korrekturfensters erneut geöffnet werden, um eine falsche Platzierung zu beheben — am Schließfach-Bildschirm oder über die API. Der correction-Block listet die wieder geöffneten Fächer auf. Jedes Fach führt zusätzlich pickup_locker_code — die Bezeichnung "{shelf_code}-{pickup_locker_number}", zu der der Empfänger geschickt wird; null, wenn das Fach keine Abholnummer hat.
Payload-BeispieleAbholcode geändert — Wird ausgelöst, wenn der Partner den Zustell- oder Abholcode einer Zustellung erneuert. Der rotation-Block nennt, welcher Code ersetzt wurde, wann, und ob die Empfängerbenachrichtigung erneut gesendet wurde — der neue Code selbst wird nie per Webhook übertragen; er wird nur in der direkten Antwort der Rotations-API offengelegt.
Payload-BeispieleCarrier-Paket verteilt — Wird ausgelöst, wenn ein an einem Lager angenommenes, avisiertes Carrier-Paket auf einen Verteilauftrag zum vom Carrier benannten Standort gesetzt wird. Der data-Block enthält Paketnummer, Carrier-Referenz und Mitgliedsnummer, den Verteilauftrag (order_id, order_ref, status) sowie Start- und Zielstandort. Nur für Carrier mit Dienstleisterkonto aufgezeichnet.
Payload-BeispieleCarrier-Paket verladen — Wird ausgelöst, wenn das Paket am Ausgangslager auf den Lkw gescannt wird; distribution.status ist in_transit, loaded_at ist gesetzt.
Payload-BeispieleCarrier-Paket am Standort zugestellt — Wird ausgelöst, wenn der Fahrer den Verteilauftrag am Standort übergibt; distribution.status ist delivered, delivered_at ist gesetzt. Die Einlagerung ist ein späteres, eigenes Ereignis.
Payload-BeispieleCarrier-Paket am Standort eingelagert — Wird ausgelöst, wenn das Paket am Standort eingelagert wird, in ein Schrankfach oder ein Regal; location enthält grid_id, grid_code und shelf_code. Die Abholbenachrichtigung an den Empfänger geht in diesem Moment hinaus.
Payload-BeispieleCarrier-Paket aus Verteilung entfernt — Wird ausgelöst, wenn das Paket vor der Abfahrt vom Verteilauftrag genommen oder der Auftrag storniert wurde; distribution.reason ist removed oder cancelled. Das Paket steht wieder auf der Verteilliste des Lagers.
Payload-BeispieleSignatur & Verifikation: Anbieter-Schließfach-Webhooks verwenden ein eigenes Signaturverfahren: X-Webhook-Signature ist base64(HMAC-SHA256(Secret, Zeitstempel + "\n" + Zustellungs-ID + "\n" + Roh-Body)), wobei Zeitstempel und Zustellungs-ID aus den Headern X-Webhook-Timestamp und X-Webhook-Delivery-Id stammen. Prüfen Sie außerdem X-Webhook-Content-Digest (SHA-256 des Bodys) und weisen Sie veraltete Zeitstempel zurück. X-Webhook-Id bleibt über Wiederholungen hinweg stabil — nutzen Sie sie für Idempotenz.
Konfiguration: Endpunkte werden unter Drittanbieter-Zustellung → Anbieter-Schließfach → Einstellungen verwaltet, ein Endpunkt pro Anbieter, mit auswählbarer Ereignisliste. Fehlgeschlagene Zustellungen werden mit exponentiellem Backoff bis zu 7-mal wiederholt, bevor sie in die Dead-Letter-Liste wandern; Dead-Letter-Ereignisse können auf der Ereignisseite manuell erneut gesendet werden.
Sandbox-Ereignisse (Mock-Schränke): Zustellungen an Mock-Schränke erzeugen dieselben Webhook-Ereignisse wie die Produktion und werden mit demselben Secret signiert, sodass Sie mit realistischem Traffic entwickeln können. Sandbox-Ereignisse sind dreifach gekennzeichnet: Die Payload enthält "livemode": false, die event_id beginnt mit PLE-MOCK- und die Anfrage trägt den Header X-Webhook-Test: 1. Ist am Endpunkt eine Sandbox-URL konfiguriert, gehen Sandbox-Ereignisse dorthin statt an die Produktions-URL; andernfalls fallen sie – weiterhin gekennzeichnet – auf die Produktions-URL zurück. Der Schalter „Sandbox-Ereignisse zustellen" stoppt die Sandbox-Zustellung vollständig.
Paketzustellungs-Webhooks, die an Drittanbieter-Zustelldienste (Kuriere) gesendet werden. Sie decken den Lebenszyklus der Zustellungszuweisungen ab, sodass ein Kurier nicht mehr nach neuen Aufträgen pollen muss. Diese Kategorie ist von den Smart-Locker-Ereignissen unten getrennt: Jeder Anbieter konfiguriert pro Kategorie einen eigenen Endpunkt, Signaturschlüssel und ein eigenes Ereignisabonnement — in seinem eigenen Anbieterportal oder durch den Plattformbetreiber.
Zuweisung erstellt — Wird ausgelöst, wenn ein Auftrag dem Anbieter zugewiesen wird — durch eine automatische Regel oder manuell. Die Nutzlast enthält die Zuweisungsnummer, Auftragskennungen und die Paket-Trackingnummern.
Payload-BeispielePakete übergeben — Wird ausgelöst, wenn das Lager alle Pakete der Zuweisung physisch an den Anbieter übergeben hat.
Payload-BeispieleZuweisung storniert — Wird ausgelöst, wenn die Plattform eine Zuweisung vom Anbieter zurückzieht. Das Feld reason unterscheidet cancelled (die Zuweisung wurde beim Frachtführer storniert), fallback_to_self_delivery (die Plattform hat den Auftrag zurück in die Eigenzustellung genommen) und reassigned (der Auftrag wurde an einen anderen Anbieter übertragen).
Payload-BeispieleTeilweise zugestellt — Wird ausgelöst, wenn ein Teil einer Sendung zugestellt wurde, während andere Pakete noch unterwegs sind. Das Array packages enthält das Ergebnis je Paket, legs listet die beim Frachtführer gebuchten externen Aufträge auf — bei Frachtführern ohne mehrstückige Sendungen einen pro Paket.
Payload-BeispieleSignatur & Verifikation: Drittanbieter-Zustell-Webhooks verwenden dasselbe Signaturverfahren wie Anbieter-Schließfach-Webhooks: X-Webhook-Signature ist base64(HMAC-SHA256(secret, timestamp + "\n" + delivery id + "\n" + raw body)), wobei timestamp und delivery id aus den Headern X-Webhook-Timestamp und X-Webhook-Delivery-Id stammen. Prüfen Sie außerdem X-Webhook-Content-Digest (SHA-256 des Bodys) und weisen Sie veraltete Zeitstempel zurück. X-Webhook-Id bleibt über Wiederholungen hinweg stabil — nutzen Sie sie für Idempotenz.
Konfiguration: Anbieter konfigurieren diesen Endpunkt selbst im Anbieterportal (Webhook-Einstellungen), oder der Plattformbetreiber tut dies unter Drittanbieter-Zustellung → Anbieter → Webhooks. Ein Endpunkt pro Anbieter mit auswählbarer Ereignisliste. Der Signaturschlüssel kann automatisch erzeugt oder als eigener Wert gesetzt werden und ist auf der Einstellungsseite einsehbar. Fehlgeschlagene Zustellungen werden mit exponentiellem Backoff bis zu 7-mal wiederholt, bevor sie in die Dead-Letter-Liste wandern; Dead-Letter-Ereignisse können manuell erneut gesendet werden. Von der Einstellungsseite kann jederzeit ein signiertes Test-Ereignis (Mock) gesendet werden — Testanfragen tragen den Header X-Webhook-Test: 1 und enthalten "test": true in den Payload-Daten.
Signierte Pushes zu Übergaben über das Open Order Handoff Protocol: Lebenszyklusänderungen (angenommen, abgelehnt, abgelaufen, storniert), Änderungsantworten, Tracking-Ereignisse und neue Abrechnungszeilen. Pro OHP-Token über POST /api/v1/ohp/subscriptions abonniert; der Endpunkt muss zuerst eine Challenge zurückgeben, bevor das Abonnement existiert. Jede Nutzlast ist der OHP-Umschlag; message_id bleibt bei jedem Wiederholungsversuch gleich — darüber deduplizieren. Pull bleibt die Quelle der Wahrheit.
Signatur & Verifikation: X-Ohp-Signature: v1= + hex HMAC-SHA256 von "{timestamp}.{raw body}" mit dem Abonnementgeheimnis. X-Ohp-Timestamp ändert sich pro Versuch; X-Ohp-Delivery entspricht message_id. CloudEvents und Standard Webhooks sind pro Abonnement verfügbar.
Konfiguration: Verwaltet mit dem OHP-Token: POST /api/v1/ohp/subscriptions (url, secret, events, format, signature), GET zum Auflisten, DELETE zum Widerrufen. Der maschinenlesbare Katalog listet jedes Ereignis unter dem Sender ohp.
Feingranulare Opt-in-Ereignisse neben dem klassischen order.status_change-Webhook (der unverändert bleibt): wer zugewiesen wurde, ob der Fahrer angenommen hat, wann das Paket abgeholt wurde, unterwegs ist, zugestellt wurde oder fehlgeschlagen ist, dazu Änderungen des Fahrerdienststatus und gedrosselte Fahrerpositionen. Es wird nichts gesendet, bis Sie die URLs unten konfigurieren.
Dem Auftrag wurde ein Fahrer zugewiesen (manuell, per Tourenplanung oder per automatischer Zuweisung). data.source = auto_assign, wenn der Orchestrator es getan hat.
Payload-BeispieleDer Auftrag hat seinen Fahrer verloren (Übergabe, Entzug, Ablehnung, Zeitüberschreitung). data.previous_driver_id gibt an, wer ihn hatte.
Payload-BeispieleDer Fahrer hat einen automatisch zugewiesenen Auftrag in der App angenommen (Fahrerdienst mit Annahmepflicht).
Payload-BeispieleDer Fahrer hat einen zugewiesenen Auftrag abgelehnt; data.reason enthält den optionalen Freitextgrund.
Payload-BeispieleDer Fahrer hat die Abholung begonnen (Status Abholung gestartet / Wird abgeholt).
Payload-BeispieleDas Paket wurde abgeholt (Status Bereits abgeholt).
Payload-BeispieleDas Paket ist unterwegs zum Empfänger (Status Zustellung gestartet / Wird zugestellt).
Payload-BeispieleDie Zustellung war erfolgreich (Status Erfolgreich).
Payload-BeispieleDer Zustellversuch ist fehlgeschlagen (Später erneut zustellen, Neuplanung erforderlich, Vom Empfänger abgelehnt).
Payload-BeispieleDer Auftrag wurde storniert.
Payload-BeispieleMitarbeiter (oder, falls zugelassen, ein Fahrer) haben den Auftrag als bereit zur Abholung markiert (Dispositionsoptionen → Bereit zur Abholung).
Payload-BeispieleEin Fahrer hat sich in der App in den Dienst oder aus dem Dienst gemeldet (Option Fahrerdienst).
Payload-BeispieleEine Fahrerposition aus der App oder vom Tracker, je Fahrer gedrosselt über driver_location_min_interval_sec (Standard 60 s). Wird nur an driver_location_webhook_url gesendet.
Payload-BeispieleKonfiguration: Einstellungen → Webhooks (oder GET/PUT /api/v1/webhook-settings, GraphQL webhookSettingsUpdate): order_lifecycle_webhook_url empfängt jedes order.*-Ereignis sowie driver.on_duty_changed; order_lifecycle_events schränkt das auf eine kommagetrennte Liste ein; driver_location_webhook_url und driver_location_min_interval_sec steuern driver.location_update. Mehrere URLs können kommagetrennt angegeben werden. Zustellungen erscheinen im Webhook-Zustellprotokoll mit reference_type order / driver.
Signatur & Verifikation: Signiert genau wie jeder andere ausgehende Webhook Ihres Kontos: Legacy-Header Signature plus X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 mit Ihrem webhook_sign_secret. Wiederholungen verwenden dieselbe event_id – deduplizieren Sie darüber.
Optionale Ereignisse für Pakete, die Ihre Paketschränke, Kioske und Smart Drops bearbeiten: ein Paket wurde im Gerät eingelagert, abgeholt, vom Personal entnommen oder hat seine Abholfrist überschritten, sowie Probleme, die dazu eröffnet oder gelöst wurden. Rein additiv — kein bestehender Webhook ändert sich, und nichts wird gesendet, bevor Sie device_order_webhook_url konfigurieren.
Ein Paket wurde in das Gerät gelegt und wartet auf die nächste Person (Empfänger, Kurier oder Betreiber, siehe data.device_order.next_actor). due_at ist die Abholfrist.
Payload-BeispieleDas Paket wurde von der Person entnommen, auf die es gewartet hat — dem Empfänger, dem Kurier oder dem Personal, das einen Smart Drop leert.
Payload-BeispieleDas Personal hat das Paket aus dem Gerät entnommen. removal_reason nennt den Grund: overdue_return, handover, relay, anomaly oder recovery.
Payload-BeispieleDas Paket hat sein due_at überschritten, ohne abgeholt zu werden. Es liegt noch im Gerät und sein Code funktioniert weiterhin; overdue_at wird gesetzt und next_actor wird zu operator.
Payload-BeispieleZu diesem Vorgang wurde ein Problem eröffnet (zum Beispiel door_left_open, deposit_unverified, item_missing, overdue). data.exception enthält id, type, severity und status.
Payload-BeispieleEine Person hat ein Problem zu diesem Vorgang geschlossen. data.exception.status ist resolved oder dismissed, und resolution_action gibt an, was getan wurde.
Payload-BeispielePayload-Beispiele: data.device_order: id, kind, status, next_actor, device_type, device_id, device_name, grid_code, reference_number, order_id, external_order_id, due_at, overdue_at, stored_at, ended_at, removal_reason (Zeiten im ISO-8601-Format, null, solange nicht erreicht). Problem-Ereignisse enthalten zusätzlich data.exception: id, type, severity, status, resolution_action. Der Abholcode ist nie enthalten. event_id lautet DOE-<Ledger-Ereignis-ID> und bleibt bei Wiederholungen gleich.
Konfiguration: Einstellungen → Webhooks (oder GET/PUT /api/v1/webhook-settings): device_order_webhook_url empfängt jedes device_order.*-Ereignis; device_order_events schränkt dies auf eine kommagetrennte Liste ein. Mehrere URLs können kommagetrennt angegeben werden. Zustellungen erscheinen im Webhook-Zustellprotokoll mit reference_type device_order.
Signatur & Verifikation: Signiert genau wie jeder andere ausgehende Webhook Ihres Kontos: Legacy-Header Signature plus X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 mit Ihrem webhook_sign_secret. Wiederholungen verwenden dieselbe event_id – deduplizieren Sie darüber.
Pakete, die ein Partner-Zusteller unter seinem eigenen Konto in Ihre Schränke liefert, werden nicht über diesen Kanal gesendet; der Partner erhält sie über seine Anbieter-Paketschrank-Webhooks.
Sie können Webhooks auf zwei Ebenen konfigurieren: auf Unternehmensebene (umfasst alles) oder pro Kunde (Override für ein bestimmtes B2B-Unterkonto).
Loggen Sie sich ein und gehen Sie zu Einstellungen → API & Webhooks. Overrides je Kunde finden Sie auf der Kundendetailseite.
Wählen Sie eine Zeichenfolge von mindestens 16 Zeichen, idealerweise 32+ zufällige Bytes. Ihr Empfänger nutzt dieses Geheimnis zur Verifikation.
Tragen Sie nur die URLs ein, die Sie benötigen. Lassen Sie den Rest leer, um diese Ereignisse zu überspringen.
webhook_sign_secretSie konfigurieren ein gemeinsames Geheimnis auf der Einstellungsseite. Jeder ausgehende Webhook wird damit signiert. Ihr Empfänger berechnet die Signatur neu und vergleicht — bei Übereinstimmung ist die Payload echt und unverändert.order_create_webhook_urlWird ausgelöst, sobald eine lokale Lieferbestellung (Delivery / Pickup / P2P) angelegt wird — über beliebigen Weg: Webformular, REST/GraphQL-API, E-Commerce-Plattform-Synchronisation, automatische Regeln, Importzeilen usw. Label-Service- und andere Nicht-Lieferarten sind ausgeschlossen. Wird im Batch-Flow übersprungen, wenn für denselben Empfänger auch order_create_async_postback_url konfiguriert ist. Konfigurieren Sie mit order_create_webhook_url.order_status_change_webhook_urlWird bei jedem Statuswechsel ausgelöst — abgeholt, unterwegs, zugestellt, Ausnahme, storniert. Konfigurieren Sie mit order_status_change_webhook_url.tracking_event_webhook_urlWird bei jedem Tracking-Lebenszyklusereignis ausgelöst (Daten übermittelt, Zustellung gestartet, erfolgreich zugestellt usw.). Konfigurieren Sie mit tracking_event_webhook_url. Zustell- und Abholereignisse enthalten außerdem den Zustellnachweis: proof_files sowie proof_files_detail (file_id, type, url, full_url, signierte Download-URL). Nach dem Ereignis hochgeladene Fotos kommen als pod.files_updated. Jede Datei trägt zusätzlich ihren Ereigniskontext: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) und service_status (1 = success / 2 = failed); bei Altdateien ohne erfasstes Ereignis sind sie null.order_create_async_postback_urlWird einmal ausgelöst, nachdem ein Stapelimport abgeschlossen ist. Payload enthält die Ergebnisse pro Zeile. Konfigurieren Sie mit order_create_async_postback_url.pod_files_webhook_urlWird ausgelöst, wenn ein Zustellfoto oder eine Unterschrift hinzugefügt, ersetzt oder entfernt wird (action: added / updated / removed) — eine Zustellung pro Datei, kein Abfragen von Anhängen mehr. Aktivierung über pod_files_webhook_url. Jede Datei trägt zusätzlich ihren Ereigniskontext: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) und service_status (1 = success / 2 = failed); bei Altdateien ohne erfasstes Ereignis sind sie null. Ersetzt ein Mitarbeiter ein Foto oder eine Unterschrift oder legt eine archivierte Version als aktuell fest, wird die Datei mit action: updated gesendet und enthält nur das aktuelle Bild; archivierte Versionen werden nie gesendet.order_deleted_webhook_urlWird ausgelöst, wenn eine Bestellung endgültig gelöscht wird, damit Ihr System die Entfernung nachvollziehen kann. Aktivierung über order_deleted_webhook_url.order_cancel_failed_webhook_urlWird ausgelöst, wenn ein Stornierungsversuch abgelehnt wird (z. B. weil die Bestellung bereits in Zustellung ist), damit Ihre Betriebsprozesse fehlgeschlagene Stornierungen ohne API-Abfragen überwachen können. Aktivierung über order_cancel_failed_webhook_url.route_board_webhook_urlWird ausgelöst, wenn ein Platz auf dem Routen-Board den Besitzer wechselt oder das Board seinen Status ändert — das Feld action sagt, was passiert ist (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Nur auf Unternehmensebene. Opt-in über route_board_webhook_url.device_order_webhook_urlOptionale Ereignisse für Pakete, die Ihre Paketschränke, Kioske und Smart Drops bearbeiten: ein Paket wurde im Gerät eingelagert, abgeholt, vom Personal entnommen oder hat seine Abholfrist überschritten, sowie Probleme, die dazu eröffnet oder gelöst wurden. Rein additiv — kein bestehender Webhook ändert sich, und nichts wird gesendet, bevor Sie device_order_webhook_url konfigurieren.Alle Neuerungen in API und Webhooks — idempotentes Stornieren, Abgleich-Feeds, v2-Signaturen, neue Events — mit Beispielen zum Kopieren. Alles vollständig abwärtskompatibel.
Jeder ausgehende Webhook enthält eine hex-codierte HMAC-SHA256-Signatur im Header. Ihr Empfänger muss die Signatur über den Roh-Body mit dem gemeinsamen Geheimnis neu berechnen und die Anfrage ablehnen, wenn sie nicht übereinstimmt.
Jede Webhook-URL kann Ereignisse im nativen Format oder als CloudEvents empfangen und zusätzlich Standard-Webhooks-Signaturheader erhalten. Dies wird pro URL in den Webhook-Einstellungen festgelegt. Eine URL ohne Einstellung empfängt Ereignisse genau wie bisher.
native — Der auf dieser Seite beschriebene JSON-Body und die Header.ce_binary — Derselbe Body; die CloudEvents-Attribute werden als ce-*-Header gesendet.ce_structured — Der Body ist ein CloudEvent (Content-Type: application/cloudevents+json) mit dem nativen Body in data. Er ist bei jedem Wiederholungsversuch identisch, und die nativen Signaturen decken ihn ab.ce-id und webhook-id enthalten die eigene event_id des Ereignisses, wenn der Body eine hat, sonst X-Webhook-Event-Id. X-Webhook-Event-Id selbst ändert sich nicht. ce-source und ce-srbusiness nennen das Unternehmen, auch bei Zustellungen an dessen Kunden.
Webhooks für Partner-Schließfachzustellungen und Drittanbieter-Zustellungen bieten dieselbe Auswahl pro Endpunkt auf der Seite der Anbieter-Webhook-Einstellungen. Ladeplan- und Open-Platform-Callbacks erhalten sie pro Anfrage: callback_format und callback_signature bzw. callback.format und callback.signature. Bei ihnen sind ce-id und webhook-id die eigene Kennung des Ereignisses (X-Webhook-Id, X-Webhook-Event-Id oder X-Open-Delivery), ce-source nennt das sendende Unternehmen, und 24 Stunden nach einer Rotation eines Anbieterschlüssels enthält webhook-signature eine Signatur pro Schlüssel.
Datensatz-Webhooks bieten dieselbe Auswahl pro Webhook im Datensatz-Webhook-Formular und in dessen API (event_format und standard_signature). Standard Webhooks verwendet den geheimen Schlüssel des Webhooks und setzt daher einen voraus. URLs von Datensatz-Webhooks müssen öffentliche HTTPS-Adressen sein.
Mit Standard Webhooks enthält jede Zustellung zusätzlich webhook-id, webhook-timestamp und webhook-signature. Sie werden bei jedem Wiederholungsversuch neu signiert, sodass auch ein Wiederholungsversuch innerhalb einer Toleranz von 5 Minuten liegt. Der Schlüssel ist Ihr Webhook-Signaturschlüssel im whsec_-Format, angezeigt auf der Einstellungsseite. Die nativen Header werden weiterhin gesendet.
Jeder Absender signiert anders. Der Headername X-Webhook-Signature wird von drei Absendern mit drei verschiedenen Verfahren verwendet; prüfen Sie mit dem Verfahren des Absenders, der Sie aufgerufen hat.
| Absender | Header | Signatur |
|---|---|---|
| Mandanten-Webhooks (diese Seite) | Content-Type, Signature, X-Webhook-Event-Id, X-Webhook-Timestamp, X-Webhook-Signature-V2 |
Signature = hex(HMAC-SHA256(body))
X-Webhook-Signature-V2 = hex(HMAC-SHA256(timestamp + "." + body)) |
| Partner-Schließfachzustellungen | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature, X-Webhook-Test |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Zuweisungen an Drittanbieter-Zustellung | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Ladeplan-Callbacks | Content-Type, X-Webhook-Event-Id, X-Webhook-Event-Type, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| Open-Platform-Job-Callbacks | Content-Type, X-Open-Event, X-Open-Delivery, X-Open-Job, X-Open-Timestamp, X-Open-Signature |
X-Open-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| OHP push | Content-Type, X-Ohp-Event, X-Ohp-Delivery, X-Ohp-Timestamp, X-Ohp-Signature |
|
| Datensatz-Webhooks | Content-Type, X-Webhook-Event, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = hex(HMAC-SHA256(body)) |
| Mandanten-Webhooks mit Standard Webhooks | webhook-id, webhook-timestamp, webhook-signature |
webhook-signature = "v1," + base64(HMAC-SHA256(webhook-id + "." + webhook-timestamp + "." + body)) |
Ihr Dienstleister kann seine Preise vor einem Kundenkonto verbergen, je Auftragsart (Lokale Lieferung, Etikettendienst, Versanddienst, LTL-Service, Lagerdienste, Umzugsservices, Geräteaufträge). Gilt das für Sie, enthalten Zustellungen an Ihren Endpunkt keine Preisfelder: shipping_price, price_details, currency, Steuern, Zuschlagsbeträge, Tarifpreise usw. werden weggelassen statt als Null gesendet. Tariflisten behalten rate_id und Servicenamen, damit ein Service weiterhin gewählt werden kann.
Ihr Endpunkt sollte schnell mit 2xx antworten. Bei anderen Antworten, Timeouts oder Nichterreichbarkeit wird die Zustellung wiederholt.
Fügen Sie eine erhaltene Payload, den Signature-Header-Wert und Ihr Geheimnis ein — das Tool berechnet die Signatur im Browser neu (nichts verlässt diese Seite) und meldet, ob sie übereinstimmt.
Senden Sie einen echten, korrekt signierten Webhook von unserem Server an eine angegebene URL. Damit prüfen Sie Erreichbarkeit, Parsing und Signaturlogik.
Sehen Sie die jüngsten Webhook-Zustellversuche Ihres Kontos — echte Produktionsereignisse und Tests von dieser Seite. Bearer-Token einfügen, um zu laden.
Zustellprotokolle werden 90 Tage aufbewahrt.
Eine manuelle erneute Zustellung erhält eine neue X-Webhook-Event-Id. Eine event_id, die das Ereignis selbst trägt (pod.files_updated, order.deleted, Lebenszyklus- und Geräteauftragsereignisse), behält ihren ursprünglichen Wert.
| Zeit | Ereignis | URL | Status | HTTP | Versuch | Zeit (ms) | Testen? | Aktionen |
|---|---|---|---|---|---|---|---|---|
| Noch keine Webhook-Zustellungen gefunden. | ||||||||