WEBHOOKS

Webhooky

Přijímejte události v reálném čase od Superroute — objednávky, změny stavu, aktualizace sledování. S podepsanými payload, automatickými opakováními a vestavěným debuggerem.

Průvodce Integrací Webhook
Centrum pro Vývojáře Domů

Průvodce Integrací Webhook

Co jsou webhooky?

Webhook je HTTP POST požadavek, který Superroute pošle na vámi nakonfigurovanou URL pokaždé, když se něco stane — vytvoří se objednávka, dokončí doručení, zaznamená událost sledování. Vy postavíte přijímací endpoint, my tam událost doručíme.

Jak doručování funguje

Události se řadí do fronty a posílají asynchronně. Každý požadavek nese podpis HMAC-SHA256 pro ověření původu. Neúspěšná doručení (ne 2xx nebo timeout) se opakují s exponenciálním backoffem až 5×.

Bezpečnostní model

Nakonfigurujete sdílené tajemství na stránce nastavení. Každý odchozí webhook se jím podepisuje. Příjemce přepočítá podpis a porovná — pokud se shodují, payload je pravý a nezměněný.

Katalog Událostí

K dispozici je osm typů odchozích událostí. Každý má vlastní URL pole na stránce nastavení — přihlaste se k libovolné podmnožině.

objednávka.vytvořený

Spustí se při vytvoření objednávky lokálního doručení (Delivery / Pickup / P2P) jakoukoli cestou: webový formulář, REST/GraphQL API, synchronizace e-commerce platformy, automatická pravidla, importované řádky atd. Vylučuje label-service a další nedoručovací typy objednávek. Přeskočeno v batch toku, pokud má stejný příjemce také nakonfigurovaný order_create_async_postback_url. Konfigurujte přes order_create_webhook_url.

Příklady Payload
objednávka.změna_stavu

Spustí se při každé změně stavu — vyzvednuto, v tranzitu, doručeno, výjimka, zrušeno. Konfigurujte přes order_status_change_webhook_url.

Příklady Payload
sledování.událost

Spustí se při každé události životního cyklu sledování balíku. Konfigurujte přes tracking_event_webhook_url. Události doručení a vyzvednutí nesou také doklad o doručení: proof_files a proof_files_detail (file_id, type, url, full_url, podepsaná URL ke stažení). Fotografie nahrané po události přicházejí jako pod.files_updated. Každý soubor nese také kontext své události: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) a service_status (1 = success / 2 = failed); u starých souborů bez zaznamenané události jsou null.

Příklady Payload
order.create_async

Spustí se jednou po dokončení dávkového importu. Payload obsahuje pole výsledků pro každý řádek. Konfigurujte přes order_create_async_postback_url.

Příklady Payload
POD soubory aktualizovány

Spustí se, když je fotografie doručení nebo podpis přidán, nahrazen či odstraněn (action: added / updated / removed) — jedno doručení na soubor, už žádné dotazování na přílohy. Aktivuje se nastavením pod_files_webhook_url. Každý soubor nese také kontext své události: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) a service_status (1 = success / 2 = failed); u starých souborů bez zaznamenané události jsou null.

Příklady Payload
Objednávka odstraněna

Spustí se při trvalém odstranění objednávky, aby ji váš systém mohl zrcadlit. Aktivuje se nastavením order_deleted_webhook_url.

Příklady Payload
Zrušení objednávky selhalo

Spustí se, když je pokus o zrušení zamítnut (například objednávka je již v doručování), aby vaše provozní procesy mohly sledovat neúspěšná zrušení bez dotazování API. Aktivuje se nastavením order_cancel_failed_webhook_url.

Příklady Payload
Změna místa na nástěnce tras

Spustí se, kdykoli místo na nástěnce tras změní držitele nebo se změní stav nástěnky — pole action říká, co se stalo (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Pouze na úrovni firmy. Přihlášení přes route_board_webhook_url.

Příklady Payload

Události poskytovatelských boxů

Samostatný webhookový kanál pro externí doručovací poskytovately integrované s chytrými boxy. Události se doručují na koncový bod nastavený pro váš poskytovatelský účet a každý koncový bod se může přihlásit k libovolné podmnožině typů událostí.

partner_locker.delivery.doors_opened

Dvířka Otevřena — Spouští se v okamžiku otevření dvířek přihrádek při pokusu o doručení — ať už kurýr zadal přístupový kód na obrazovce boxu, nebo použil API vzdáleného otevření — včetně opětovných otevření po přeřazení. Blok opening uvádí každou otevřenou přihrádku s grid_id, hardwarovým číslem dvířek compartment_number a pickup_locker_number (pořadové zobrazovací číslo počítané shora dolů v každém sloupci a poté zleva doprava). Každá přihrádka nese i pickup_locker_code — označení "{shelf_code}-{pickup_locker_number}", ke kterému je příjemce nasměrován; null, pokud přihrádka nemá číslo vyzvednutí. Obsah zprávy zahrnuje také pickup_code — kód pro vyzvednutí určený příjemci, přidělený v okamžiku otevření dvířek; po potvrzení vložení kurýrem zůstává stejným kódem a k vyzvednutí jej lze použít až po tomto potvrzení.

Příklady Payload
partner_locker.delivery.delivered

Doručeno do boxu — Spustí se, když je uložení potvrzeno a balíky jsou v boxu. Obsah zahrnuje kód pro vyzvednutí příjemcem. Každá přihrádka nese i pickup_locker_code — označení "{shelf_code}-{pickup_locker_number}", ke kterému je příjemce nasměrován; null, pokud přihrádka nemá číslo vyzvednutí. U dvířek otevřených přes API dálkového otevírání platforma uložení uzavře sama, jakmile box nahlásí zavření všech otevřených dvířek, takže událost se spustí i bez volání confirm; confirmed_by označuje cestu uzavření: courier_terminal, partner_api, door_close, timeout_door_closed nebo console.

Příklady Payload
partner_locker.pickup.completed

Vyzvednuto — Spustí se, když si příjemce vyzvedl uložené balíky.

Příklady Payload
partner_locker.delivery.failed

Doručení selhalo — Spustí se, když doručení selže; zahrnuty jsou kódy selhání pro jednotlivé balíky.

Příklady Payload
partner_locker.delivery.expired

Platnost vypršela — Spustí se, když nepoužitý doručovací kód nebo nevyzvednuté uložení překročí dobu platnosti.

Příklady Payload
partner_locker.delivery.cancelled

Zrušeno — Spustí se, když je doručení zrušeno před dokončením.

Příklady Payload
partner_locker.delivery.correction_reopened

Opravné otevření — Spustí se, když se obsazené schránky znovu otevřou v rámci opravného okna k nápravě chybného uložení — z obrazovky boxu nebo přes API. Blok correction uvádí znovu otevřené schránky. Každá přihrádka nese i pickup_locker_code — označení "{shelf_code}-{pickup_locker_number}", ke kterému je příjemce nasměrován; null, pokud přihrádka nemá číslo vyzvednutí.

Příklady Payload
partner_locker.delivery.code_rotated

partner_locker_delivery.event_type_code_rotated — Spouští se, když partner vymění doručovací nebo vyzvedávací kód doručení. Blok rotation uvádí, který kód byl nahrazen, kdy a zda bylo znovu odesláno upozornění příjemci — nový kód nikdy necestuje webhookem; odhalí se pouze v přímé odpovědi API na výměnu.

Příklady Payload

Podpis a Ověření: Webhooky poskytovatelských boxů používají vlastní schéma podepisování: X-Webhook-Signature je base64(HMAC-SHA256(tajemství, časové razítko + "\n" + id doručení + "\n" + surové tělo)), přičemž časové razítko a id doručení pocházejí z hlaviček X-Webhook-Timestamp a X-Webhook-Delivery-Id. Ověřte také X-Webhook-Content-Digest (SHA-256 těla) a odmítejte zastaralá časová razítka. X-Webhook-Id zůstává stabilní napříč opakováními — použijte ho pro idempotenci.

Jak Konfigurovat: Koncové body se spravují v části Doručování třetích stran → Poskytovatelský box → Nastavení, jeden koncový bod na poskytovatele, s volitelným seznamem událostí. Neúspěšná doručení se opakují s exponenciálním odstupem až 7krát, než skončí v mrtvé schránce; události z mrtvé schránky lze ručně znovu odeslat ze stránky událostí.

Sandbox události (testovací skříňky): Doručení vytvořená na testovacích skříňkách emitují stejné webhook události jako produkce, podepsané stejným tajemstvím, takže můžete vyvíjet s realistickým provozem. Sandbox události jsou označeny třemi způsoby: obsah nese "livemode": false, event_id začíná předponou PLE-MOCK- a požadavek obsahuje hlavičku X-Webhook-Test: 1. Pokud je na koncovém bodě nastavena sandbox adresa, sandbox události směřují tam místo produkční adresy; jinak se vrátí na produkční adresu, stále označené. Přepínač „Doručovat sandbox události" zcela zastaví sandbox doručování.

Události doručování třetích stran

Webhooky doručování balíků odesílané externím poskytovatelům doručování (kurýrům). Pokrývají životní cyklus přidělení doručení, takže kurýr už nemusí nové úkoly zjišťovat dotazováním. Tato kategorie je oddělená od událostí Smart Locker níže: každý poskytovatel konfiguruje nezávislý koncový bod, podpisový tajný klíč a odběr událostí pro každou kategorii — ve vlastním portálu nebo prostřednictvím operátora platformy.

delivery.assignment.created

Přidělení vytvořeno — Spustí se, když je objednávka přidělena poskytovateli — automatickým pravidlem nebo ručně. Payload obsahuje číslo přidělení, identifikátory objednávky a sledovací čísla balíků.

Příklady Payload
delivery.assignment.handed_over

Balíky předány — Spustí se, když sklad fyzicky předal poskytovateli všechny balíky přidělení.

Příklady Payload
delivery.assignment.cancelled

Přidělení zrušeno — Spustí se, když platforma stáhne přidělení od poskytovatele. Pole reason rozlišuje: cancelled (přidělení bylo zrušeno u dopravce), fallback_to_self_delivery (platforma převzala objednávku zpět do vlastního doručování) a reassigned (objednávka byla přesunuta k jinému poskytovateli).

Příklady Payload
delivery.assignment.partial_delivered

Částečné doručení — Spustí se, když byla část zásilky doručena, zatímco ostatní balíky jsou stále na cestě. Pole packages obsahuje výsledek každého balíku a legs uvádí externí objednávky zadané u dopravce — po jedné na balík, pokud dopravce nepřijímá vícekusové zásilky.

Příklady Payload

Podpis a Ověření: Webhooky doručování třetích stran používají stejné schéma podepisování jako webhooky poskytovatelských boxů: X-Webhook-Signature je base64(HMAC-SHA256(secret, timestamp + "\n" + delivery id + "\n" + raw body)), přičemž timestamp a delivery id pocházejí z hlaviček X-Webhook-Timestamp a X-Webhook-Delivery-Id. Ověřte také X-Webhook-Content-Digest (SHA-256 těla) a odmítejte zastaralá časová razítka. X-Webhook-Id zůstává stabilní napříč opakováními — použijte jej pro idempotenci.

Jak Konfigurovat: Poskytovatelé si tento koncový bod konfigurují sami v portálu poskytovatele (Nastavení webhooků), nebo tak učiní operátor platformy v části Doručování třetích stran → Poskytovatelé → Webhooks. Jeden koncový bod na poskytovatele s volitelným seznamem událostí. Podpisový tajný klíč lze vygenerovat automaticky nebo nastavit na vlastní hodnotu a je k nahlédnutí na stránce nastavení. Neúspěšná doručení se opakují s exponenciálním odstupem až 7krát, než skončí v mrtvé schránce; události z mrtvé schránky lze opakovat ručně. Ze stránky nastavení lze kdykoli odeslat podepsanou testovací (mock) událost — testovací požadavky nesou hlavičku X-Webhook-Test: 1 a obsahují "test": true v datech payloadu.

Události životního cyklu objednávky

Podrobné, volitelné události vedle klasického webhooku order.status_change (který zůstává beze změny): kdo byl přiřazen, zda řidič přijal, kdy byl balík vyzvednut, na cestě, doručen nebo neúspěšný, plus změny služby řidičů a frekvenčně omezené polohy řidičů. Nic se neodesílá, dokud nenastavíte URL adresy níže.

order.assigned

K objednávce byl přiřazen řidič (ručně, plánováním tras nebo automatickým přiřazením). data.source = auto_assign, když to provedl orchestrátor.

Příklady Payload
order.unassigned

Objednávka přišla o svého řidiče (předání, odebrání, odmítnutí, vypršení času). data.previous_driver_id uvádí, kdo ji měl.

Příklady Payload
order.accepted

Řidič v aplikaci přijal automaticky přiřazenou objednávku (služba řidičů s povinným přijetím).

Příklady Payload
order.rejected

Řidič odmítl přiřazenou objednávku; data.reason obsahuje volitelný důvod ve volném textu.

Příklady Payload
order.pickup_started

Řidič zahájil vyzvednutí (stav Zahájení vyzvednutí / Vyzvedává se).

Příklady Payload
order.picked_up

Balík byl vyzvednut (stav Již vyzvednuto).

Příklady Payload
order.on_the_way

Balík je na cestě k příjemci (stav Zahájení doručení / Doručuje se).

Příklady Payload
order.completed

Doručení bylo úspěšné (stav Úspěšné).

Příklady Payload
order.failed

Pokus o doručení selhal (Doručit později, Vyžaduje přeplánování, Odmítnuto příjemcem).

Příklady Payload
order.cancelled

Objednávka byla zrušena.

Příklady Payload
order.ready

Zaměstnanec (nebo řidič, pokud je to povoleno) označil objednávku jako připravenou k vyzvednutí (Možnosti dispečinku → Připraveno k vyzvednutí).

Příklady Payload
driver.on_duty_changed

Řidič v aplikaci nastoupil do služby nebo ji ukončil (možnost služba řidičů).

Příklady Payload
driver.location_update

Poloha řidiče z aplikace nebo trackeru, omezená na řidiče pomocí driver_location_min_interval_sec (výchozí 60 s). Odesílá se pouze na driver_location_webhook_url.

Příklady Payload

Jak Konfigurovat: Nastavení → Webhooky (nebo GET/PUT /api/v1/webhook-settings, GraphQL webhookSettingsUpdate): order_lifecycle_webhook_url přijímá každou událost order.* a driver.on_duty_changed; order_lifecycle_events to zužuje na seznam oddělený čárkami; driver_location_webhook_url a driver_location_min_interval_sec řídí driver.location_update. Více URL adres lze oddělit čárkami. Doručení se zobrazují v protokolu doručení webhooků s reference_type order / driver.

Podpis a Ověření: Podepsáno přesně jako každý jiný odchozí webhook vašeho účtu: původní hlavička Signature plus X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 s vaším webhook_sign_secret. Opakované pokusy používají stejné event_id – deduplikujte podle něj.

Události objednávek v zařízeních

Volitelné události pro zásilky zpracované vašimi chytrými schránkami, kiosky a smart drop boxy: zásilka uložená do zařízení, vyzvednutá, vyjmutá personálem nebo po termínu vyzvednutí a také problémy otevřené nebo vyřešené v souvislosti s ní. Pouze rozšíření — žádný stávající webhook se nemění a nic se neodešle, dokud nenastavíte device_order_webhook_url.

device_order.stored

Zásilka byla vložena do zařízení a čeká na další osobu (příjemce, kurýra nebo provozovatele, viz data.device_order.next_actor). due_at je termín vyzvednutí.

Příklady Payload
device_order.collected

Zásilku vyjmula osoba, na kterou čekala — příjemce, kurýr nebo personál vyprazdňující smart drop box.

Příklady Payload
device_order.removed

Personál vyjmul zásilku ze zařízení. removal_reason uvádí důvod: overdue_return, handover, relay, anomaly nebo recovery.

Příklady Payload
device_order.overdue

Zásilka překročila due_at bez vyzvednutí. Je stále v zařízení a její kód stále funguje; nastaví se overdue_at a next_actor se změní na operator.

Příklady Payload
device_order.exception_opened

Ke zpracování byl otevřen problém (například door_left_open, deposit_unverified, item_missing, overdue). data.exception obsahuje id, type, severity a status.

Příklady Payload
device_order.exception_resolved

Někdo uzavřel problém zpracování. data.exception.status je resolved nebo dismissed a resolution_action uvádí, co bylo provedeno.

Příklady Payload

Příklady 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 (časy ve formátu ISO 8601, null, dokud nenastanou). Události problémů přidávají data.exception: id, type, severity, status, resolution_action. Kód pro vyzvednutí se nikdy neuvádí. event_id má tvar DOE-<id události registru> a při opakovaných pokusech se nemění.

Jak Konfigurovat: Nastavení → Webhooky (nebo GET/PUT /api/v1/webhook-settings): device_order_webhook_url přijímá každou událost device_order.*; device_order_events ji zužuje na seznam oddělený čárkami. Více URL adres lze oddělit čárkami. Doručení se zobrazují v protokolu doručení webhooků s reference_type device_order.

Podpis a Ověření: Podepsáno přesně jako každý jiný odchozí webhook vašeho účtu: původní hlavička Signature plus X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 s vaším webhook_sign_secret. Opakované pokusy používají stejné event_id – deduplikujte podle něj.

Zásilky, které partnerský dopravce doručí do vašich schránek pod vlastním účtem, se tímto kanálem neodesílají; partner je dostává přes vlastní webhooky schránek poskytovatele.

Jak Konfigurovat

Webhooky můžete konfigurovat na dvou úrovních: na úrovni firmy (zahrnuje vše) nebo na úrovni zákazníka (přepisuje pro daný B2B podúčet).

1. Přejděte do nastavení

Přihlaste se a přejděte do Nastavení → API a Webhooky. Přepisy na úrovni zákazníka jsou na stránce detailu zákazníka.

2. Nastavte tajemství podpisu

Zvolte řetězec alespoň 16 znaků, ideálně 32+ náhodných bajtů. Příjemce ho použije k ověření podpisů.

3. Nastavte požadované URL událostí

Vyplňte pouze URL událostí, které vás zajímají. Ostatní nechte prázdné.

webhook_sign_secretNakonfigurujete sdílené tajemství na stránce nastavení. Každý odchozí webhook se jím podepisuje. Příjemce přepočítá podpis a porovná — pokud se shodují, payload je pravý a nezměněný.
order_create_webhook_urlSpustí se při vytvoření objednávky lokálního doručení (Delivery / Pickup / P2P) jakoukoli cestou: webový formulář, REST/GraphQL API, synchronizace e-commerce platformy, automatická pravidla, importované řádky atd. Vylučuje label-service a další nedoručovací typy objednávek. Přeskočeno v batch toku, pokud má stejný příjemce také nakonfigurovaný order_create_async_postback_url. Konfigurujte přes order_create_webhook_url.
order_status_change_webhook_urlSpustí se při každé změně stavu — vyzvednuto, v tranzitu, doručeno, výjimka, zrušeno. Konfigurujte přes order_status_change_webhook_url.
tracking_event_webhook_urlSpustí se při každé události životního cyklu sledování balíku. Konfigurujte přes tracking_event_webhook_url. Události doručení a vyzvednutí nesou také doklad o doručení: proof_files a proof_files_detail (file_id, type, url, full_url, podepsaná URL ke stažení). Fotografie nahrané po události přicházejí jako pod.files_updated. Každý soubor nese také kontext své události: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) a service_status (1 = success / 2 = failed); u starých souborů bez zaznamenané události jsou null.
order_create_async_postback_urlSpustí se jednou po dokončení dávkového importu. Payload obsahuje pole výsledků pro každý řádek. Konfigurujte přes order_create_async_postback_url.
pod_files_webhook_urlSpustí se, když je fotografie doručení nebo podpis přidán, nahrazen či odstraněn (action: added / updated / removed) — jedno doručení na soubor, už žádné dotazování na přílohy. Aktivuje se nastavením pod_files_webhook_url. Každý soubor nese také kontext své události: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) a service_status (1 = success / 2 = failed); u starých souborů bez zaznamenané události jsou null.
order_deleted_webhook_urlSpustí se při trvalém odstranění objednávky, aby ji váš systém mohl zrcadlit. Aktivuje se nastavením order_deleted_webhook_url.
order_cancel_failed_webhook_urlSpustí se, když je pokus o zrušení zamítnut (například objednávka je již v doručování), aby vaše provozní procesy mohly sledovat neúspěšná zrušení bez dotazování API. Aktivuje se nastavením order_cancel_failed_webhook_url.
route_board_webhook_urlSpustí se, kdykoli místo na nástěnce tras změní držitele nebo se změní stav nástěnky — pole action říká, co se stalo (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Pouze na úrovni firmy. Přihlášení přes route_board_webhook_url.
device_order_webhook_urlVolitelné události pro zásilky zpracované vašimi chytrými schránkami, kiosky a smart drop boxy: zásilka uložená do zařízení, vyzvednutá, vyjmutá personálem nebo po termínu vyzvednutí a také problémy otevřené nebo vyřešené v souvislosti s ní. Pouze rozšíření — žádný stávající webhook se nemění a nic se neodešle, dokud nenastavíte device_order_webhook_url.
Průvodce novinkami integrace

Všechny novinky v API a webhoocích — idempotentní zrušení, feedy pro odsouhlasení, podpisy v2, nové události — s příklady ke zkopírování. Vše plně zpětně kompatibilní.

Podpis a Ověření

Každý odchozí webhook nese hex-kódovaný podpis HMAC-SHA256 v hlavičce. Příjemce musí znovu vypočítat podpis nad surovým tělem se sdíleným tajemstvím a odmítnout požadavek, pokud se neshoduje.

Algoritmus
HMAC-SHA256 (hex)
Název hlavičky
Signature
Kroky ověření
  1. Přečtěte surové tělo dříve, než ho parsing nebo middleware upraví.
  2. Vypočítejte hash_hmac('sha256', rawBody, sharedSecret) a kódujte v hex.
  3. Porovnejte s hlavičkou Signature v konstantním čase (hash_equals v PHP, crypto.timingSafeEqual v Node).
  4. Odpovězte 2xx pouze pokud se podpisy shodují. Jinak 401.
<?php $rawBody = file_get_contents('php://input'); $received = $_SERVER['HTTP_SIGNATURE'] ?? ''; $expected = hash_hmac('sha256', $rawBody, $sharedSecret); if (!hash_equals($expected, $received)) { http_response_code(401); exit('Bad signature'); } $payload = json_decode($rawBody, true); // ... handle event ... http_response_code(200); echo 'ok';
const crypto = require('crypto'); const express = require('express'); const app = express(); app.use('/webhooks/superroute', express.raw({ type: 'application/json' }), (req, res) => { const received = req.header('Signature') || ''; const expected = crypto.createHmac('sha256', sharedSecret) .update(req.body).digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))) { return res.status(401).send('Bad signature'); } const payload = JSON.parse(req.body.toString()); // ... handle event ... res.status(200).send('ok'); });
import hmac, hashlib from flask import Flask, request, abort app = Flask(__name__) @app.route('/webhooks/superroute', methods=['POST']) def webhook(): received = request.headers.get('Signature', '') expected = hmac.new(shared_secret.encode(), request.data, hashlib.sha256).hexdigest() if not hmac.compare_digest(received, expected): abort(401) payload = request.get_json() # ... handle event ... return 'ok', 200
func handleWebhook(w http.ResponseWriter, r *http.Request) { body, _ := io.ReadAll(r.Body) received := r.Header.Get("Signature") mac := hmac.New(sha256.New, []byte(sharedSecret)) mac.Write(body) expected := hex.EncodeToString(mac.Sum(nil)) if !hmac.Equal([]byte(received), []byte(expected)) { w.WriteHeader(401); return } // ... handle event ... w.WriteHeader(200) w.Write([]byte("ok")) }
require 'openssl' require 'rack/utils' post '/webhooks/superroute' do raw = request.body.read received = request.env['HTTP_SIGNATURE'] || '' expected = OpenSSL::HMAC.hexdigest('sha256', shared_secret, raw) halt 401 unless Rack::Utils.secure_compare(received, expected) payload = JSON.parse(raw) # ... handle event ... status 200 'ok' end

Opakování a Spolehlivost

Váš endpoint by měl rychle odpovědět 2xx. Jinak, při timeoutu nebo nedostupnosti, se doručení opakuje.

Max. pokusů
5 (počáteční + 4 opakování)
Timeout na pokus
3 sekundy
Ústup
Exponenciální — cca 10s, 100s, 1000s, 10000s
Stavte na idempotenci. Protože se doručení může opakovat, příjemce může vidět stejnou událost vícekrát. Použijte ID objednávky/sledování jako klíč pro deduplikaci — uchovávejte zpracovaná ID alespoň 24 hodin.
Doporučená odpověď. Rychle potvrďte (HTTP 200) a zpracujte asynchronně. Vyhněte se pomalým operacím synchronně v handleru — narazíte na 3sekundový timeout.

Ověřovač Podpisu

Vložte přijatý payload, hodnotu hlavičky Signature a vaše tajemství — nástroj přepočítá podpis v prohlížeči (nic neopustí tuto stránku) a oznámí, zda se shodují.

Odeslat Testovací Webhook

Spusťte skutečný, správně podepsaný webhook z našeho serveru na URL, kterou zadáte. Užitečné pro testování dostupnosti příjemce, parsování payload a logiky ověření podpisu.

Poslední Doručení Webhook

Zobrazte si nejnovější pokusy o doručení webhook na vašem účtu — produkční události i testy z této stránky. Vložte Bearer token pro načtení.

Čas Událost URL Stav HTTP Pokus Čas (ms) Testovat? Akce
Zatím žádná doručení webhook.

Nejlepší Praxe

© 2026 superRoute. Centrum pro Vývojáře