WEBHOOKS
Webhooki
Otrzymuj zdarzenia w czasie rzeczywistym od Superroute — zamówienia, zmiany statusu, aktualizacje śledzenia. Z podpisanymi payload-ami, automatycznymi ponowieniami i wbudowanym debuggerem.
WEBHOOKS
Otrzymuj zdarzenia w czasie rzeczywistym od Superroute — zamówienia, zmiany statusu, aktualizacje śledzenia. Z podpisanymi payload-ami, automatycznymi ponowieniami i wbudowanym debuggerem.
Webhook to żądanie HTTP POST, które Superroute wysyła na skonfigurowany przez Ciebie URL przy każdym zdarzeniu — utworzenie zamówienia, zakończenie dostawy, zarejestrowanie zdarzenia śledzenia. Ty budujesz endpoint odbiorczy, my dostarczamy tam zdarzenie.
Zdarzenia są kolejkowane i wysyłane asynchronicznie. Każde żądanie zawiera podpis HMAC-SHA256 do weryfikacji pochodzenia. Nieudane dostarczenia (nie 2xx lub timeout) są ponawiane z wykładniczym backoff do 5 razy.
Konfigurujesz wspólny sekret na stronie ustawień. Każdy wychodzący webhook jest nim podpisywany. Twój odbiorca przelicza podpis i porównuje — jeśli się zgadzają, payload jest autentyczny i nietknięty.
Dostępnych jest osiem typów zdarzeń wychodzących. Każdy ma własne pole URL na stronie ustawień — subskrybuj dowolny podzbiór.
Czytelny maszynowo opis wszystkich zdarzeń wychodzących ze schematami treści, nagłówkami i harmonogramami ponowień (AsyncAPI 3.0): asyncapi-webhooks.json
Wyzwala się przy utworzeniu zamówienia dostawy lokalnej (Delivery / Pickup / P2P) dowolną drogą: formularz web, REST/GraphQL API, synchronizacja platformy e-commerce, automatyczne reguły, wiersze importu itd. Wyklucza zamówienia label-service i inne typy nie-dostawcze. Pomijany w przepływie batch, gdy ten sam odbiorca ma również skonfigurowany order_create_async_postback_url. Konfiguruj za pomocą order_create_webhook_url.
Przykłady PayloadWyzwala się przy każdej zmianie statusu — odebrane, w tranzycie, dostarczone, wyjątek, anulowane. Konfiguruj za pomocą order_status_change_webhook_url.
Przykłady PayloadWyzwala się przy każdym zdarzeniu cyklu życia śledzenia paczki. Konfiguruj za pomocą tracking_event_webhook_url. Zdarzenia doręczenia i odbioru zawierają także potwierdzenie doręczenia: proof_files oraz proof_files_detail (file_id, type, url, full_url, podpisany adres pobrania). Zdjęcia wgrane po zdarzeniu przychodzą jako pod.files_updated. Każdy plik zawiera też kontekst swojego zdarzenia: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) oraz service_status (1 = success / 2 = failed); dla starych plików bez zapisanego zdarzenia są null.
Przykłady PayloadWyzwala się raz po zakończeniu przetwarzania importu wsadowego. Payload zawiera tablicę wyników na wiersz. Konfiguruj za pomocą order_create_async_postback_url.
Przykłady PayloadWyzwalane, gdy zdjęcie dostawy lub podpis zostanie dodany, zastąpiony lub usunięty (action: added / updated / removed) — jedna wysyłka na plik, koniec z odpytywaniem o załączniki. Włączane przez pod_files_webhook_url. Każdy plik zawiera też kontekst swojego zdarzenia: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) oraz service_status (1 = success / 2 = failed); dla starych plików bez zapisanego zdarzenia są null. Gdy pracownik zastąpi zdjęcie lub podpis albo ustawi zarchiwizowaną wersję jako bieżącą, plik jest wysyłany z action: updated i zawiera tylko bieżący obraz; zarchiwizowane wersje nigdy nie są wysyłane.
Przykłady PayloadWyzwalane, gdy zamówienie zostanie trwale usunięte, aby Twój system mógł odzwierciedlić usunięcie. Włączane przez order_deleted_webhook_url.
Przykłady PayloadWyzwalane, gdy próba anulowania zostanie odrzucona (np. zamówienie jest już w doręczeniu), aby Twoje procesy operacyjne mogły monitorować nieudane anulowania bez odpytywania API. Włączane przez order_cancel_failed_webhook_url.
Przykłady PayloadWyzwalane, gdy miejsce na tablicy tras zmienia właściciela lub tablica zmienia stan — pole action mówi, co się stało (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Tylko na poziomie firmy. Subskrypcja przez route_board_webhook_url.
Przykłady PayloadOsobny kanał webhooków dla zewnętrznych dostawcaów doręczeń zintegrowanych z inteligentnymi skrytkami. Zdarzenia trafiają do punktu końcowego skonfigurowanego dla Twojego konta dostawcy, a każdy punkt końcowy może subskrybować dowolny podzbiór typów zdarzeń.
Drzwiczki Otwarte — Uruchamia się w momencie otwarcia drzwiczek skrytek dla próby doręczenia — niezależnie od tego, czy kurier wpisał kod dostępu na ekranie automatu, czy użył API zdalnego otwierania — w tym ponowne otwarcia po zmianie skrytki. Blok opening wymienia każdą otwartą skrytkę z grid_id, sprzętowym numerem drzwiczek compartment_number oraz pickup_locker_number (kolejnym numerem wyświetlania liczonym od góry do dołu w kolumnie, a następnie od lewej do prawej). Każda skrytka zawiera też pickup_locker_code — etykietę "{shelf_code}-{pickup_locker_number}", pod którą kierowany jest odbiorca; null, gdy skrytka nie ma numeru odbioru. Ładunek zawiera również pickup_code — kod odbioru dla odbiorcy, przydzielany w chwili otwarcia drzwiczek; po potwierdzeniu umieszczenia przesyłki przez kuriera pozostaje tym samym kodem, a do odbioru można go użyć dopiero po tym potwierdzeniu.
Przykłady PayloadDostarczono do paczkomatu — Wyzwalane, gdy umieszczenie przesyłki zostanie potwierdzone i paczki są w skrytce. Ładunek zawiera kod odbioru odbiorcy. Każda skrytka zawiera też pickup_locker_code — etykietę "{shelf_code}-{pickup_locker_number}", pod którą kierowany jest odbiorca; null, gdy skrytka nie ma numeru odbioru. W przypadku skrytek otwartych przez API zdalnego otwierania platforma sama rozlicza umieszczenie, gdy tylko szafka zgłosi zamknięcie wszystkich otwartych skrytek, więc zdarzenie jest wyzwalane bez wywołania confirm; confirmed_by wskazuje ścieżkę rozliczenia: courier_terminal, partner_api, door_close, timeout_door_closed lub console.
Przykłady PayloadOdebrano — Wyzwalane, gdy odbiorca odebrał umieszczone paczki.
Przykłady PayloadDostawa nieudana — Wyzwalane, gdy doręczenie się nie powiedzie; dołączone są kody błędów dla poszczególnych paczek.
Przykłady PayloadWygasło — Wyzwalane, gdy niewykorzystany kod doręczenia lub nieodebrana przesyłka przekroczy termin ważności.
Przykłady PayloadAnulowano — Wyzwalane, gdy doręczenie zostanie anulowane przed ukończeniem.
Przykłady PayloadPonowne otwarcie korekcyjne — Wyzwalane, gdy zajęte skrytki zostaną ponownie otwarte w oknie korekty w celu poprawienia błędnego umieszczenia — z ekranu skrytki lub przez API. Blok correction wymienia ponownie otwarte skrytki. Każda skrytka zawiera też pickup_locker_code — etykietę "{shelf_code}-{pickup_locker_number}", pod którą kierowany jest odbiorca; null, gdy skrytka nie ma numeru odbioru.
Przykłady PayloadKod odbioru zmieniony — Uruchamia się, gdy partner wymienia kod doręczenia albo kod odbioru przesyłki. Blok rotation wskazuje, który kod wymieniono, kiedy i czy ponownie wysłano powiadomienie do odbiorcy — nowy kod nigdy nie podróżuje w webhooku; ujawniany jest wyłącznie w bezpośredniej odpowiedzi API wymiany.
Przykłady PayloadPaczka przewoźnika przekazana do dystrybucji — Uruchamiane, gdy awizowana paczka przewoźnika przyjęta w jednym magazynie zostaje umieszczona na zleceniu dystrybucji do lokalizacji wskazanej przez przewoźnika. Blok data zawiera numer paczki, referencję przewoźnika i numer członkowski, zlecenie dystrybucji (order_id, order_ref, status) oraz lokalizację początkową i docelową. Rejestrowane tylko dla przewoźników z kontem dostawcy.
Przykłady PayloadPaczka przewoźnika załadowana — Uruchamiane, gdy paczka zostaje zeskanowana na ciężarówkę w magazynie początkowym; distribution.status to in_transit, a loaded_at jest ustawione.
Przykłady PayloadPaczka przewoźnika dostarczona do lokalizacji — Uruchamiane, gdy kierowca przekazuje zlecenie dystrybucji w lokalizacji; distribution.status to delivered, a delivered_at jest ustawione. Odłożenie jest późniejszym, osobnym zdarzeniem.
Przykłady PayloadPaczka przewoźnika odłożona w lokalizacji — Uruchamiane, gdy paczka zostaje odłożona w lokalizacji, do skrytki lub na półkę; location zawiera grid_id, grid_code i shelf_code. Powiadomienie odbiorcy o odbiorze wychodzi w tym momencie.
Przykłady PayloadPaczka przewoźnika usunięta z dystrybucji — Uruchamiane, gdy paczka zostaje zdjęta ze zlecenia dystrybucji przed wyjazdem lub zlecenie zostaje anulowane; distribution.reason to removed lub cancelled. Paczka wraca na listę dystrybucji magazynu.
Przykłady PayloadPodpis i Weryfikacja: Webhooki skrytek dostawcaskich używają własnego schematu podpisu: X-Webhook-Signature to base64(HMAC-SHA256(sekret, znacznik czasu + "\n" + id doręczenia + "\n" + surowa treść)), gdzie znacznik czasu i id doręczenia pochodzą z nagłówków X-Webhook-Timestamp i X-Webhook-Delivery-Id. Zweryfikuj też X-Webhook-Content-Digest (SHA-256 treści) i odrzucaj przeterminowane znaczniki czasu. X-Webhook-Id pozostaje stały między ponowieniami — użyj go do idempotencji.
Jak Skonfigurować: Punkty końcowe zarządzane są w Doręczenia zewnętrzne → Skrytka dostawcy → Ustawienia, jeden punkt końcowy na dostawcy, z wybieralną listą zdarzeń. Nieudane dostarczenia są ponawiane z wykładniczym odstępem do 7 razy, zanim trafią do martwej kolejki; zdarzenia z martwej kolejki można ręcznie wysłać ponownie ze strony zdarzeń.
Zdarzenia sandbox (makiety szafek): Dostarczenia utworzone na makietach szafek emitują te same zdarzenia webhook co produkcja, podpisane tym samym sekretem, dzięki czemu można rozwijać integrację na realistycznym ruchu. Zdarzenia sandbox są oznaczone na trzy sposoby: ładunek zawiera "livemode": false, event_id zaczyna się od PLE-MOCK-, a żądanie niesie nagłówek X-Webhook-Test: 1. Jeśli na punkcie końcowym skonfigurowano adres sandbox, zdarzenia sandbox trafiają tam zamiast na adres produkcyjny; w przeciwnym razie wracają na adres produkcyjny, nadal oznaczone. Przełącznik „Dostarczaj zdarzenia sandbox" całkowicie zatrzymuje dostarczanie sandbox.
Webhooki doręczeń paczek wysyłane do zewnętrznych dostawców doręczeń (kurierów). Obejmują cykl życia przydziałów doręczeń, dzięki czemu kurier nie musi już odpytywać o nowe zlecenia. Ta kategoria jest oddzielna od poniższych zdarzeń Smart Locker: każdy dostawca konfiguruje niezależny endpoint, sekret podpisu i subskrypcję zdarzeń dla każdej kategorii — we własnym portalu lub przez operatora platformy.
Przydział utworzony — Wyzwalane, gdy zamówienie zostaje przydzielone dostawcy — regułą automatyczną lub ręcznie. Payload zawiera numer przydziału, identyfikatory zamówienia i numery śledzenia paczek.
Przykłady PayloadPaczki przekazane — Wyzwalane, gdy magazyn fizycznie przekazał dostawcy wszystkie paczki przydziału.
Przykłady PayloadPrzydział anulowany — Wyzwalane, gdy platforma wycofuje przydział od dostawcy. Pole reason rozróżnia: cancelled (przydział anulowano u przewoźnika), fallback_to_self_delivery (platforma przejęła zamówienie z powrotem do doręczeń własnych) oraz reassigned (zamówienie przeniesiono do innego dostawcy).
Przykłady PayloadDostawa częściowa — Uruchamia się, gdy część przesyłki została dostarczona, a pozostałe paczki są nadal w drodze. Tablica packages zawiera wynik każdej paczki, a legs wymienia zamówienia zewnętrzne złożone u przewoźnika — po jednym na paczkę, gdy przewoźnik nie przyjmuje przesyłek wielopaczkowych.
Przykłady PayloadPodpis i Weryfikacja: Webhooki doręczeń zewnętrznych używają tego samego schematu podpisu co webhooki skrytek dostawcaskich: X-Webhook-Signature to base64(HMAC-SHA256(secret, timestamp + "\n" + delivery id + "\n" + raw body)), przy czym timestamp i delivery id pochodzą z nagłówków X-Webhook-Timestamp i X-Webhook-Delivery-Id. Zweryfikuj także X-Webhook-Content-Digest (SHA-256 treści) i odrzucaj przeterminowane znaczniki czasu. X-Webhook-Id pozostaje stały między ponowieniami — używaj go do idempotencji.
Jak Skonfigurować: Dostawcy konfigurują ten endpoint samodzielnie w portalu dostawcy (Ustawienia webhooków) lub robi to operator platformy w Doręczenia zewnętrzne → Dostawcy → Webhooks. Jeden endpoint na dostawcę z wybieralną listą zdarzeń. Sekret podpisu może być generowany automatycznie lub ustawiony jako wartość niestandardowa i jest widoczny na stronie ustawień. Nieudane dostarczenia są ponawiane z wykładniczym odstępem do 7 razy, zanim trafią do martwej kolejki; zdarzenia z martwej kolejki można ponowić ręcznie. Ze strony ustawień można w każdej chwili wysłać podpisane zdarzenie testowe (mock) — żądania testowe niosą nagłówek X-Webhook-Test: 1 i zawierają "test": true w danych payloadu.
Podpisane pushe o przekazaniach wymienianych przez Open Order Handoff Protocol: zmiany cyklu życia (przyjęte, odrzucone, wygasłe, anulowane), odpowiedzi na poprawki, zdarzenia śledzenia i nowe pozycje rozliczeń. Subskrybowane per token OHP przez POST /api/v1/ohp/subscriptions; endpoint musi najpierw odbić challenge, zanim subskrypcja zaistnieje. Każdy ładunek to koperta OHP; message_id pozostaje takie samo przy każdej ponownej próbie — deduplikuj po nim. Pull pozostaje źródłem prawdy.
Podpis i Weryfikacja: X-Ohp-Signature: v1= + szesnastkowy HMAC-SHA256 z "{timestamp}.{raw body}" z sekretem subskrypcji. X-Ohp-Timestamp zmienia się przy każdej próbie; X-Ohp-Delivery równa się message_id. CloudEvents i Standard Webhooks są dostępne per subskrypcja.
Jak Skonfigurować: Zarządzane tokenem OHP: POST /api/v1/ohp/subscriptions (url, secret, events, format, signature), GET aby wylistować, DELETE aby odwołać. Katalog czytelny maszynowo wymienia każde zdarzenie pod nadawcą ohp.
Szczegółowe, opcjonalne zdarzenia obok klasycznego webhooka order.status_change (który pozostaje bez zmian): kto został przypisany, czy kierowca zaakceptował, kiedy paczka została odebrana, jest w drodze, dostarczona lub nieudana, a także zmiany dyżurów kierowców i ograniczone częstotliwościowo pozycje kierowców. Nic nie jest wysyłane, dopóki nie skonfigurujesz poniższych adresów URL.
Do zamówienia przypisano kierowcę (ręcznie, przez planowanie tras lub przez automatyczne przypisywanie). data.source = auto_assign, gdy zrobił to orkiestrator.
Przykłady PayloadZamówienie straciło kierowcę (przekazanie, cofnięcie, odrzucenie, przekroczenie czasu). data.previous_driver_id wskazuje, kto je miał.
Przykłady PayloadKierowca zaakceptował w aplikacji automatycznie przypisane zamówienie (dyżury kierowców z wymaganą akceptacją).
Przykłady PayloadKierowca odrzucił przypisane zamówienie; data.reason zawiera opcjonalny powód w formie dowolnego tekstu.
Przykłady PayloadKierowca rozpoczął odbiór (status Rozpoczęto odbiór / W odbiorze).
Przykłady PayloadPaczka została odebrana (status Już odebrane).
Przykłady PayloadPaczka jest w drodze do odbiorcy (status Rozpoczęto dostawę / W dostawie).
Przykłady PayloadDostawa zakończyła się powodzeniem (status Zakończone sukcesem).
Przykłady PayloadPróba dostawy nie powiodła się (Doręczyć później, Wymaga zmiany terminu, Odrzucone przez odbiorcę).
Przykłady PayloadZamówienie zostało anulowane.
Przykłady PayloadPersonel (lub kierowca, jeśli dozwolone) oznaczył zamówienie jako gotowe do odbioru (Opcje dyspozycji → gotowe do odbioru).
Przykłady PayloadKierowca rozpoczął lub zakończył dyżur w aplikacji (opcja dyżurów kierowców).
Przykłady PayloadPozycja kierowcy z aplikacji lub lokalizatora, ograniczana per kierowca przez driver_location_min_interval_sec (domyślnie 60 s). Wysyłana tylko na driver_location_webhook_url.
Przykłady PayloadJak Skonfigurować: Ustawienia → Webhooki (lub GET/PUT /api/v1/webhook-settings, GraphQL webhookSettingsUpdate): order_lifecycle_webhook_url otrzymuje każde zdarzenie order.* oraz driver.on_duty_changed; order_lifecycle_events zawęża to do listy rozdzielonej przecinkami; driver_location_webhook_url i driver_location_min_interval_sec sterują driver.location_update. Kilka adresów URL można rozdzielić przecinkami. Doręczenia pojawiają się w dzienniku doręczeń webhooków z reference_type order / driver.
Podpis i Weryfikacja: Podpisywane dokładnie tak jak każdy inny wychodzący webhook Twojego konta: starszy nagłówek Signature oraz X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 z Twoim webhook_sign_secret. Ponowne próby używają tego samego event_id – deduplikuj na jego podstawie.
Opcjonalne zdarzenia dla paczek obsługiwanych przez Twoje inteligentne szafki, kioski i skrzynki smart drop: paczka umieszczona w urządzeniu, odebrana, wyjęta przez personel lub po terminie odbioru, a także problemy otwarte lub rozwiązane w jej sprawie. Wyłącznie rozszerzenie — żaden istniejący webhook się nie zmienia i nic nie jest wysyłane, dopóki nie skonfigurujesz device_order_webhook_url.
Paczka została umieszczona w urządzeniu i czeka na kolejną osobę (odbiorcę, kuriera lub operatora, zobacz data.device_order.next_actor). due_at to termin odbioru.
Przykłady PayloadPaczkę wyjęła osoba, na którą czekała — odbiorca, kurier lub personel opróżniający skrzynkę smart drop.
Przykłady PayloadPersonel wyjął paczkę z urządzenia. removal_reason podaje powód: overdue_return, handover, relay, anomaly lub recovery.
Przykłady PayloadPaczka przekroczyła due_at bez odbioru. Nadal jest w urządzeniu, a jej kod wciąż działa; ustawiane jest overdue_at, a next_actor zmienia się na operator.
Przykłady PayloadOtwarto problem dotyczący obsługi (na przykład door_left_open, deposit_unverified, item_missing, overdue). data.exception zawiera id, type, severity i status.
Przykłady PayloadOsoba zamknęła problem dotyczący obsługi. data.exception.status ma wartość resolved lub dismissed, a resolution_action określa, co zrobiono.
Przykłady PayloadPrzykłady Payload: 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 (czasy w formacie ISO 8601, null, dopóki nie nastąpią). Zdarzenia problemów dodają data.exception: id, type, severity, status, resolution_action. Kod odbioru nigdy nie jest dołączany. event_id ma postać DOE-<id zdarzenia rejestru> i nie zmienia się przy ponownych próbach.
Jak Skonfigurować: Ustawienia → Webhooki (lub GET/PUT /api/v1/webhook-settings): device_order_webhook_url otrzymuje każde zdarzenie device_order.*; device_order_events zawęża to do listy rozdzielonej przecinkami. Można podać kilka adresów URL rozdzielonych przecinkami. Dostarczenia pojawiają się w dzienniku dostarczeń webhooków z reference_type device_order.
Podpis i Weryfikacja: Podpisywane dokładnie tak jak każdy inny wychodzący webhook Twojego konta: starszy nagłówek Signature oraz X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 z Twoim webhook_sign_secret. Ponowne próby używają tego samego event_id – deduplikuj na jego podstawie.
Paczki, które przewoźnik partnerski dostarcza do Twoich szafek na własnym koncie, nie są wysyłane tym kanałem; partner otrzymuje je przez własne webhooki szafek dostawcy.
Webhooki można konfigurować na dwóch poziomach: firmy (obejmuje wszystko) lub klienta (nadpisuje dla konkretnego subkonta B2B).
Zaloguj się i przejdź do Ustawienia → API i Webhooki. Nadpisania per klient są na stronie szczegółów klienta.
Wybierz ciąg co najmniej 16-znakowy, najlepiej 32+ losowych bajtów. Odbiorca użyje go do weryfikacji podpisów.
Wypełnij tylko URL-e zdarzeń, którymi jesteś zainteresowany. Resztę pozostaw pustą.
webhook_sign_secretKonfigurujesz wspólny sekret na stronie ustawień. Każdy wychodzący webhook jest nim podpisywany. Twój odbiorca przelicza podpis i porównuje — jeśli się zgadzają, payload jest autentyczny i nietknięty.Order_create_webhook_urlWyzwala się przy utworzeniu zamówienia dostawy lokalnej (Delivery / Pickup / P2P) dowolną drogą: formularz web, REST/GraphQL API, synchronizacja platformy e-commerce, automatyczne reguły, wiersze importu itd. Wyklucza zamówienia label-service i inne typy nie-dostawcze. Pomijany w przepływie batch, gdy ten sam odbiorca ma również skonfigurowany order_create_async_postback_url. Konfiguruj za pomocą order_create_webhook_url.Order_status_change_webhook_urlWyzwala się przy każdej zmianie statusu — odebrane, w tranzycie, dostarczone, wyjątek, anulowane. Konfiguruj za pomocą order_status_change_webhook_url.śledzenia_event_webhook_urlWyzwala się przy każdym zdarzeniu cyklu życia śledzenia paczki. Konfiguruj za pomocą tracking_event_webhook_url. Zdarzenia doręczenia i odbioru zawierają także potwierdzenie doręczenia: proof_files oraz proof_files_detail (file_id, type, url, full_url, podpisany adres pobrania). Zdjęcia wgrane po zdarzeniu przychodzą jako pod.files_updated. Każdy plik zawiera też kontekst swojego zdarzenia: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) oraz service_status (1 = success / 2 = failed); dla starych plików bez zapisanego zdarzenia są null.Order_create_async_postback_urlWyzwala się raz po zakończeniu przetwarzania importu wsadowego. Payload zawiera tablicę wyników na wiersz. Konfiguruj za pomocą order_create_async_postback_url.pod_files_webhook_urlWyzwalane, gdy zdjęcie dostawy lub podpis zostanie dodany, zastąpiony lub usunięty (action: added / updated / removed) — jedna wysyłka na plik, koniec z odpytywaniem o załączniki. Włączane przez pod_files_webhook_url. Każdy plik zawiera też kontekst swojego zdarzenia: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) oraz service_status (1 = success / 2 = failed); dla starych plików bez zapisanego zdarzenia są null. Gdy pracownik zastąpi zdjęcie lub podpis albo ustawi zarchiwizowaną wersję jako bieżącą, plik jest wysyłany z action: updated i zawiera tylko bieżący obraz; zarchiwizowane wersje nigdy nie są wysyłane.order_deleted_webhook_urlWyzwalane, gdy zamówienie zostanie trwale usunięte, aby Twój system mógł odzwierciedlić usunięcie. Włączane przez order_deleted_webhook_url.order_cancel_failed_webhook_urlWyzwalane, gdy próba anulowania zostanie odrzucona (np. zamówienie jest już w doręczeniu), aby Twoje procesy operacyjne mogły monitorować nieudane anulowania bez odpytywania API. Włączane przez order_cancel_failed_webhook_url.route_board_webhook_urlWyzwalane, gdy miejsce na tablicy tras zmienia właściciela lub tablica zmienia stan — pole action mówi, co się stało (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Tylko na poziomie firmy. Subskrypcja przez route_board_webhook_url.device_order_webhook_urlOpcjonalne zdarzenia dla paczek obsługiwanych przez Twoje inteligentne szafki, kioski i skrzynki smart drop: paczka umieszczona w urządzeniu, odebrana, wyjęta przez personel lub po terminie odbioru, a także problemy otwarte lub rozwiązane w jej sprawie. Wyłącznie rozszerzenie — żaden istniejący webhook się nie zmienia i nic nie jest wysyłane, dopóki nie skonfigurujesz device_order_webhook_url.Wszystkie nowości w API i webhookach — idempotentne anulowanie, kanały uzgodnień, podpisy v2, nowe zdarzenia — z gotowymi przykładami. Wszystko w pełni wstecznie kompatybilne.
Każdy wychodzący webhook zawiera podpis HMAC-SHA256 w formacie hex w nagłówku. Odbiorca musi ponownie obliczyć podpis na surowym body z użyciem wspólnego sekretu i odrzucić żądanie, jeśli się nie zgadza.
Każdy adres URL webhooka może otrzymywać zdarzenia w formacie natywnym lub jako CloudEvents, a także nagłówki podpisu Standard Webhooks. Ustawia się to osobno dla każdego adresu w ustawieniach webhooków. Adres bez ustawienia otrzymuje zdarzenia dokładnie tak jak dotąd.
native — Treść JSON i nagłówki opisane na tej stronie.ce_binary — Ta sama treść; atrybuty CloudEvents są wysyłane jako nagłówki ce-*.ce_structured — Treść jest zdarzeniem CloudEvent (Content-Type: application/cloudevents+json), a treść natywna znajduje się w data. Jest identyczna przy każdej ponownej próbie i obejmują ją podpisy natywne.ce-id i webhook-id zawierają własne event_id zdarzenia, gdy treść je ma, w przeciwnym razie X-Webhook-Event-Id. Samo X-Webhook-Event-Id się nie zmienia. ce-source i ce-srbusiness wskazują firmę, także przy dostawach do jej klientów.
Webhooki dostaw do skrytek partnerów i dostawy zewnętrznej oferują ten sam wybór dla każdego endpointu, na stronie ustawień webhooków dostawcy. Wywołania zwrotne planów załadunku i Open Platform otrzymują go w każdym żądaniu: callback_format i callback_signature lub callback.format i callback.signature. W ich przypadku ce-id i webhook-id to własny identyfikator zdarzenia (X-Webhook-Id, X-Webhook-Event-Id lub X-Open-Delivery), ce-source wskazuje firmę wysyłającą, a przez 24 godziny po rotacji klucza dostawcy webhook-signature zawiera po jednym podpisie na klucz.
Webhooki zbiorów danych oferują ten sam wybór dla każdego webhooka, w formularzu webhooka i w jego API (event_format i standard_signature). Standard Webhooks używa klucza tajnego webhooka, więc jest on wymagany. Adresy URL webhooków zbiorów danych muszą być publicznymi adresami HTTPS.
Przy Standard Webhooks każda dostawa zawiera również webhook-id, webhook-timestamp i webhook-signature. Są podpisywane ponownie przy każdej ponownej próbie, więc ponowna próba mieści się w tolerancji 5 minut. Kluczem jest klucz podpisu webhooka w formie whsec_, widoczny na stronie ustawień. Nagłówki natywne są nadal wysyłane.
Każdy nadawca podpisuje inaczej. Nazwy nagłówka X-Webhook-Signature używa trzech nadawców z trzema różnymi metodami; weryfikuj metodą nadawcy, który Cię wywołał.
| Nadawca | Nagłówki | Podpis |
|---|---|---|
| Webhooki najemcy (ta strona) | 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)) |
| Dostawy do skrytek partnerów | 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)) |
| Przydziały do dostawy zewnętrznej | 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)) |
| Wywołania zwrotne planów załadunku | 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)) |
| Wywołania zwrotne zadań Open Platform | 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 |
|
| Webhooki zbiorów danych | Content-Type, X-Webhook-Event, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = hex(HMAC-SHA256(body)) |
| Webhooki najemcy z Standard Webhooks | webhook-id, webhook-timestamp, webhook-signature |
webhook-signature = "v1," + base64(HMAC-SHA256(webhook-id + "." + webhook-timestamp + "." + body)) |
Twój dostawca usług może ukryć swoje ceny przed kontem klienta, według rodziny zamówień (Dostawa lokalna, Usługa etykiet, Usługa kurierska, Usługa LTL, Usługi przechowywania, Usługi przeprowadzkowe, zamówienia urządzeń). Gdy to Cię dotyczy, dostawy do Twojego punktu końcowego nie zawierają pól cenowych: shipping_price, price_details, currency, podatek, kwoty dopłat, ceny stawek itp. są pomijane, a nie wysyłane jako zero. Listy stawek zachowują rate_id i nazwy usług, aby nadal można było wybrać usługę.
Twój endpoint powinien szybko odpowiedzieć 2xx. W przeciwnym razie, przy timeout lub nieosiągalności, dostarczenie jest ponawiane.
Wklej otrzymany payload, wartość nagłówka Signature i swój sekret — narzędzie przelicza podpis w przeglądarce (nic nie opuszcza tej strony) i mówi, czy się zgadza.
Wystrzel prawdziwy, poprawnie podpisany webhook z naszego serwera na podany przez Ciebie URL. Użyj do testowania osiągalności odbiorcy, parsowania payload i logiki weryfikacji podpisu.
Zobacz ostatnie próby dostarczenia webhook na Twoim koncie — zarówno rzeczywiste zdarzenia produkcyjne, jak i testy z tej strony. Wklej Bearer token, aby wczytać.
Rejestry dostarczeń są przechowywane przez 90 dni.
Ręczne ponowne dostarczenie otrzymuje nowe X-Webhook-Event-Id. event_id przenoszone przez samo zdarzenie (pod.files_updated, order.deleted, zdarzenia cyklu życia i zamówień urządzeń) zachowuje pierwotną wartość.
| Czas | Zdarzenie | URL | Stan | HTTP | Próba | Czas (ms) | Testować? | Akcje |
|---|---|---|---|---|---|---|---|---|
| Brak dostarczeń webhook. | ||||||||