WEBHOOKS

Webhooky

Prijímajte udalosti v reálnom čase od Superroute — objednávky, zmeny stavu, aktualizácie sledovania. S podpísanými payload-mi, automatickými opakovaniami a vstavaným debugerom.

Sprievodca Integráciou Webhook
Centrum pre Vývojárov Domov

Sprievodca Integráciou Webhook

Čo sú webhooky?

Webhook je HTTP POST požiadavka, ktorú Superroute pošle na vami nakonfigurovanú URL vždy, keď sa niečo stane — vytvorí sa objednávka, dokončí doručenie, zaeviduje udalosť sledovania. Vy postavíte prijímací endpoint, my tam udalosť doručíme.

Ako funguje doručenie

Udalosti sa zaraďujú do frontu a posielajú sa asynchrónne. Každá požiadavka nesie HMAC-SHA256 podpis na overenie pôvodu. Neúspešné doručenia (nie 2xx alebo timeout) sa opakujú s exponenciálnym backoffom až 5-krát.

Bezpečnostný model

Nakonfigurujete zdieľané tajomstvo na stránke nastavení. Každý odchádzajúci webhook sa ním podpíše. Váš príjemca prepočíta podpis a porovná — ak sa zhodujú, payload je pravý a nezmenený.

Katalóg Udalostí

K dispozícii je osem typov odchádzajúcich udalostí. Každý má vlastné URL pole na stránke nastavení — prihláste sa na ľubovoľnú podmnožinu.

objednávka.vytvorený

Spustí sa pri vytvorení objednávky lokálneho doručenia (Delivery / Pickup / P2P) akoukoľvek cestou: web formulár, REST/GraphQL API, synchronizácia e-commerce platformy, automatické pravidlá, importované riadky atď. Vylučuje label-service a iné nedoručovacie typy objednávok. Preskočené v batch toku, ak má rovnaký príjemca tiež nakonfigurovaný order_create_async_postback_url. Konfigurujte cez order_create_webhook_url.

Príklady Payload
objednávka.zmena_stavu

Spustí sa pri každej zmene stavu — vyzdvihnuté, v tranzite, doručené, výnimka, zrušené. Konfigurujte cez order_status_change_webhook_url.

Príklady Payload
sledovanie.udalosť

Spustí sa pri každej udalosti životného cyklu sledovania balíka. Konfigurujte cez tracking_event_webhook_url. Udalosti doručenia a vyzdvihnutia obsahujú aj doklad o doručení: proof_files a proof_files_detail (file_id, type, url, full_url, podpísaná URL na stiahnutie). Fotografie nahraté po udalosti prichádzajú ako pod.files_updated. Každý súbor nesie aj kontext svojej udalosti: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) a service_status (1 = success / 2 = failed); pri starých súboroch bez zaznamenanej udalosti sú null.

Príklady Payload
order.create_async

Spustí sa raz po dokončení spracovania dávkového importu. Payload obsahuje pole výsledkov na riadok. Konfigurujte cez order_create_async_postback_url.

Príklady Payload
POD súbory aktualizované

Spustí sa, keď sa fotografia doručenia alebo podpis pridá, nahradí alebo odstráni (action: added / updated / removed) — jedno doručenie na súbor, už žiadne dopytovanie príloh. Aktivuje sa nastavením pod_files_webhook_url. Každý súbor nesie aj kontext svojej udalosti: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) a service_status (1 = success / 2 = failed); pri starých súboroch bez zaznamenanej udalosti sú null.

Príklady Payload
Objednávka odstránená

Spustí sa pri trvalom odstránení objednávky, aby ju váš systém mohol zrkadliť. Aktivuje sa nastavením order_deleted_webhook_url.

Príklady Payload
Zrušenie objednávky zlyhalo

Spustí sa, keď je pokus o zrušenie zamietnutý (napríklad objednávka je už v doručovaní), aby vaše prevádzkové procesy mohli sledovať neúspešné zrušenia bez dopytovania API. Aktivuje sa nastavením order_cancel_failed_webhook_url.

Príklady Payload
Zmena miesta na nástenke trás

Spustí sa, keď miesto na nástenke trás zmení držiteľa alebo sa zmení stav nástenky — pole action hovorí, čo sa stalo (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Iba na úrovni firmy. Prihlásenie cez route_board_webhook_url.

Príklady Payload

Udalosti poskytovateľských skriniek

Samostatný webhookový kanál pre externých doručovacích poskytovateľov integrovaných s inteligentnými skrinkami. Udalosti sa doručujú na koncový bod nastavený pre váš poskytovateľský účet a každý koncový bod sa môže prihlásiť na ľubovoľnú podmnožinu typov udalostí.

partner_locker.delivery.doors_opened

Dvierka Otvorené — Spúšťa sa v okamihu otvorenia dvierok priehradiek pri pokuse o doručenie — či už kuriér zadal prístupový kód na obrazovke boxu, alebo použil API vzdialeného otvorenia — vrátane opätovných otvorení po preradení. Blok opening uvádza každú otvorenú priehradku s grid_id, hardvérovým číslom dvierok compartment_number a pickup_locker_number (poradové zobrazovacie číslo počítané zhora nadol v každom stĺpci a potom zľava doprava). Každá priehradka nesie aj pickup_locker_code — označenie "{shelf_code}-{pickup_locker_number}", ku ktorému je príjemca nasmerovaný; null, ak priehradka nemá číslo vyzdvihnutia. Obsah správy zahŕňa aj pickup_code — kód na vyzdvihnutie pre príjemcu, pridelený v okamihu otvorenia dvierok; po potvrdení vloženia kuriérom zostáva tým istým kódom a na vyzdvihnutie ho možno použiť až po tomto potvrdení.

Príklady Payload
partner_locker.delivery.delivered

Doručené do boxu — Spustí sa, keď je uloženie potvrdené a balíky sú v skrinke. Obsah zahŕňa kód na vyzdvihnutie pre príjemcu. Každá priehradka nesie aj pickup_locker_code — označenie "{shelf_code}-{pickup_locker_number}", ku ktorému je príjemca nasmerovaný; null, ak priehradka nemá číslo vyzdvihnutia. Pri dvierkach otvorených cez API diaľkového otvárania platforma uloženie uzavrie sama, len čo skrinka nahlási zatvorenie všetkých otvorených dvierok, takže udalosť sa spustí aj bez volania confirm; confirmed_by označuje cestu uzavretia: courier_terminal, partner_api, door_close, timeout_door_closed alebo console.

Príklady Payload
partner_locker.pickup.completed

Vyzdvihnuté — Spustí sa, keď si príjemca vyzdvihol uložené balíky.

Príklady Payload
partner_locker.delivery.failed

Doručenie zlyhalo — Spustí sa, keď doručenie zlyhá; zahrnuté sú kódy zlyhania pre jednotlivé balíky.

Príklady Payload
partner_locker.delivery.expired

Platnosť vypršala — Spustí sa, keď nepoužitý doručovací kód alebo nevyzdvihnuté uloženie prekročí čas platnosti.

Príklady Payload
partner_locker.delivery.cancelled

Zrušené — Spustí sa, keď je doručenie zrušené pred dokončením.

Príklady Payload
partner_locker.delivery.correction_reopened

Opravné otvorenie — Spustí sa, keď sa obsadené priehradky znovu otvoria v rámci opravného okna na nápravu nesprávneho uloženia — z obrazovky skrinky alebo cez API. Blok correction uvádza znovu otvorené priehradky. Každá priehradka nesie aj pickup_locker_code — označenie "{shelf_code}-{pickup_locker_number}", ku ktorému je príjemca nasmerovaný; null, ak priehradka nemá číslo vyzdvihnutia.

Príklady Payload
partner_locker.delivery.code_rotated

partner_locker_delivery.event_type_code_rotated — Spúšťa sa, keď partner vymení doručovací alebo vyzdvihávací kód doručenia. Blok rotation uvádza, ktorý kód bol nahradený, kedy a či bolo znova odoslané upozornenie príjemcovi — nový kód nikdy necestuje webhookom; odhalí sa len v priamej odpovedi API na výmenu.

Príklady Payload

Podpis a Overenie: Webhooky poskytovateľských skriniek používajú vlastnú schému podpisovania: X-Webhook-Signature je base64(HMAC-SHA256(tajomstvo, časová pečiatka + "\n" + id doručenia + "\n" + surové telo)), pričom časová pečiatka a id doručenia pochádzajú z hlavičiek X-Webhook-Timestamp a X-Webhook-Delivery-Id. Overte aj X-Webhook-Content-Digest (SHA-256 tela) a odmietnite zastarané časové pečiatky. X-Webhook-Id zostáva stabilné počas opakovaní — použite ho na idempotenciu.

Ako Konfigurovať: Koncové body sa spravujú v časti Doručovanie tretích strán → Poskytovateľská skrinka → Nastavenia, jeden koncový bod na poskytovateľa, s voliteľným zoznamom udalostí. Neúspešné doručenia sa opakujú s exponenciálnym odstupom až 7-krát, kým skončia v mŕtvej schránke; udalosti z mŕtvej schránky možno ručne znovu odoslať zo stránky udalostí.

Sandbox udalosti (testovacie skrinky): Doručenia vytvorené na testovacích skrinkách emitujú rovnaké webhook udalosti ako produkcia, podpísané rovnakým tajomstvom, takže môžete vyvíjať s realistickou prevádzkou. Sandbox udalosti sú označené tromi spôsobmi: obsah nesie "livemode": false, event_id začína predponou PLE-MOCK- a požiadavka obsahuje hlavičku X-Webhook-Test: 1. Ak je na koncovom bode nastavená sandbox adresa, sandbox udalosti smerujú tam namiesto produkčnej adresy; inak sa vrátia na produkčnú adresu, stále označené. Prepínač „Doručovať sandbox udalosti" úplne zastaví sandbox doručovanie.

Udalosti doručovania tretích strán

Webhooky doručovania balíkov odosielané externým poskytovateľom doručovania (kuriérom). Pokrývajú životný cyklus pridelení doručenia, takže kuriér už nemusí nové úlohy zisťovať dopytovaním. Táto kategória je oddelená od udalostí Smart Locker nižšie: každý poskytovateľ konfiguruje nezávislý koncový bod, podpisový tajný kľúč a odber udalostí pre každú kategóriu — vo vlastnom portáli alebo prostredníctvom operátora platformy.

delivery.assignment.created

Pridelenie vytvorené — Spustí sa, keď je objednávka pridelená poskytovateľovi — automatickým pravidlom alebo ručne. Payload obsahuje číslo pridelenia, identifikátory objednávky a sledovacie čísla balíkov.

Príklady Payload
delivery.assignment.handed_over

Balíky odovzdané — Spustí sa, keď sklad fyzicky odovzdal poskytovateľovi všetky balíky pridelenia.

Príklady Payload
delivery.assignment.cancelled

Pridelenie zrušené — Spustí sa, keď platforma stiahne pridelenie od poskytovateľa. Pole reason rozlišuje: cancelled (pridelenie bolo zrušené u prepravcu), fallback_to_self_delivery (platforma prevzala objednávku späť do vlastného doručovania) a reassigned (objednávka bola presunutá k inému poskytovateľovi).

Príklady Payload
delivery.assignment.partial_delivered

Čiastočné doručenie — Spustí sa, keď bola časť zásielky doručená, zatiaľ čo ostatné balíky sú stále na ceste. Pole packages obsahuje výsledok každého balíka a legs uvádza externé objednávky zadané u dopravcu — po jednej na balík, ak dopravca neprijíma viackusové zásielky.

Príklady Payload

Podpis a Overenie: Webhooky doručovania tretích strán používajú rovnakú schému podpisovania ako webhooky poskytovateľských skriniek: X-Webhook-Signature je base64(HMAC-SHA256(secret, timestamp + "\n" + delivery id + "\n" + raw body)), pričom timestamp a delivery id pochádzajú z hlavičiek X-Webhook-Timestamp a X-Webhook-Delivery-Id. Overte aj X-Webhook-Content-Digest (SHA-256 tela) a odmietnite zastarané časové pečiatky. X-Webhook-Id zostáva stabilný počas opakovaní — použite ho na idempotenciu.

Ako Konfigurovať: Poskytovatelia si tento koncový bod konfigurujú sami v portáli poskytovateľa (Nastavenia webhookov), alebo tak urobí operátor platformy v časti Doručovanie tretích strán → Poskytovatelia → Webhooks. Jeden koncový bod na poskytovateľa s voliteľným zoznamom udalostí. Podpisový tajný kľúč sa môže vygenerovať automaticky alebo nastaviť na vlastnú hodnotu a je viditeľný na stránke nastavení. Neúspešné doručenia sa opakujú s exponenciálnym odstupom až 7-krát, kým skončia v mŕtvej schránke; udalosti z mŕtvej schránky možno opakovať ručne. Zo stránky nastavení možno kedykoľvek odoslať podpísanú testovaciu (mock) udalosť — testovacie požiadavky nesú hlavičku X-Webhook-Test: 1 a obsahujú "test": true v dátach payloadu.

Udalosti životného cyklu objednávky

Podrobné, voliteľné udalosti popri klasickom webhooku order.status_change (ktorý zostáva nezmenený): kto bol priradený, či vodič prijal, kedy bol balík vyzdvihnutý, na ceste, doručený alebo neúspešný, plus zmeny služby vodičov a frekvenčne obmedzené polohy vodičov. Nič sa neposiela, kým nenastavíte URL adresy nižšie.

order.assigned

K objednávke bol priradený vodič (manuálne, plánovaním trás alebo automatickým priradením). data.source = auto_assign, keď to urobil orchestrátor.

Príklady Payload
order.unassigned

Objednávka stratila svojho vodiča (odovzdanie, odobratie, odmietnutie, vypršanie času). data.previous_driver_id uvádza, kto ju mal.

Príklady Payload
order.accepted

Vodič v aplikácii prijal automaticky priradenú objednávku (služba vodičov s povinným prijatím).

Príklady Payload
order.rejected

Vodič odmietol priradenú objednávku; data.reason obsahuje voliteľný dôvod vo voľnom texte.

Príklady Payload
order.pickup_started

Vodič začal vyzdvihnutie (stav Vyzdvihnutie začaté / Na vyzdvihnutie).

Príklady Payload
order.picked_up

Balík bol vyzdvihnutý (stav Už vyzdvihnuté).

Príklady Payload
order.on_the_way

Balík je na ceste k príjemcovi (stav Doručenie začaté / Na doručenie).

Príklady Payload
order.completed

Doručenie bolo úspešné (stav Úspešné).

Príklady Payload
order.failed

Pokus o doručenie zlyhal (Doručiť neskôr, Vyžaduje preplánovanie, Odmietnuté príjemcom).

Príklady Payload
order.cancelled

Objednávka bola zrušená.

Príklady Payload
order.ready

Personál (alebo vodič, ak je to povolené) označil objednávku ako pripravenú na vyzdvihnutie (Možnosti dispečingu → pripravené na vyzdvihnutie).

Príklady Payload
driver.on_duty_changed

Vodič v aplikácii nastúpil do služby alebo ju ukončil (možnosť služba vodičov).

Príklady Payload
driver.location_update

Poloha vodiča z aplikácie alebo trackera, obmedzená na vodiča pomocou driver_location_min_interval_sec (predvolene 60 s). Posiela sa iba na driver_location_webhook_url.

Príklady Payload

Ako Konfigurovať: Nastavenia → Webhooky (alebo GET/PUT /api/v1/webhook-settings, GraphQL webhookSettingsUpdate): order_lifecycle_webhook_url prijíma každú udalosť order.* a driver.on_duty_changed; order_lifecycle_events to zužuje na zoznam oddelený čiarkami; driver_location_webhook_url a driver_location_min_interval_sec riadia driver.location_update. Viacero URL adries možno oddeliť čiarkami. Doručenia sa zobrazujú v denníku doručení webhookov s reference_type order / driver.

Podpis a Overenie: Podpísané presne ako každý iný odchádzajúci webhook vášho úč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ú rovnaké event_id – deduplikujte podľa neho.

Udalosti objednávok v zariadeniach

Voliteľné udalosti pre zásielky spracované vašimi inteligentnými schránkami, kioskmi a smart drop boxmi: zásielka uložená do zariadenia, vyzdvihnutá, vybraná personálom alebo po termíne vyzdvihnutia, ako aj problémy otvorené alebo vyriešené v súvislosti s ňou. Iba rozšírenie — žiadny existujúci webhook sa nemení a nič sa neodošle, kým nenastavíte device_order_webhook_url.

device_order.stored

Zásielka bola vložená do zariadenia a čaká na ďalšiu osobu (príjemcu, kuriéra alebo prevádzkovateľa, pozri data.device_order.next_actor). due_at je termín vyzdvihnutia.

Príklady Payload
device_order.collected

Zásielku vybrala osoba, na ktorú čakala — príjemca, kuriér alebo personál vyprázdňujúci smart drop box.

Príklady Payload
device_order.removed

Personál vybral zásielku zo zariadenia. removal_reason uvádza dôvod: overdue_return, handover, relay, anomaly alebo recovery.

Príklady Payload
device_order.overdue

Zásielka prekročila due_at bez vyzdvihnutia. Stále je v zariadení a jej kód stále funguje; nastaví sa overdue_at a next_actor sa zmení na operator.

Príklady Payload
device_order.exception_opened

Pre spracovanie bol otvorený problém (napríklad door_left_open, deposit_unverified, item_missing, overdue). data.exception obsahuje id, type, severity a status.

Príklady Payload
device_order.exception_resolved

Niekto uzavrel problém spracovania. data.exception.status je resolved alebo dismissed a resolution_action uvádza, čo sa urobilo.

Príklady Payload

Prí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 vo formáte ISO 8601, null, kým nenastanú). Udalosti problémov pridávajú data.exception: id, type, severity, status, resolution_action. Kód na vyzdvihnutie sa nikdy neuvádza. event_id má tvar DOE-<id udalosti registra> a pri opakovaných pokusoch sa nemení.

Ako Konfigurovať: Nastavenia → Webhooky (alebo GET/PUT /api/v1/webhook-settings): device_order_webhook_url prijíma každú udalosť device_order.*; device_order_events ju zužuje na zoznam oddelený čiarkami. Viacero URL adries možno oddeliť čiarkami. Doručenia sa zobrazujú v denníku doručení webhookov s reference_type device_order.

Podpis a Overenie: Podpísané presne ako každý iný odchádzajúci webhook vášho úč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ú rovnaké event_id – deduplikujte podľa neho.

Zásielky, ktoré partnerský dopravca doručí do vašich schránok pod vlastným účtom, sa týmto kanálom neodosielajú; partner ich dostáva cez vlastné webhooky schránok poskytovateľa.

Ako Konfigurovať

Webhooky môžete konfigurovať na dvoch úrovniach: na úrovni firmy (pokrýva všetko) alebo na úrovni zákazníka (prepíše pre daný B2B podúčet).

1. Prejdite do nastavení

Prihláste sa a prejdite do Nastavenia → API a Webhooky. Prepisy na úrovni zákazníka sú na stránke detailov zákazníka.

2. Nastavte tajomstvo podpisu

Vyberte reťazec aspoň 16 znakov, ideálne 32+ náhodných bajtov. Príjemca ho použije na overenie podpisov.

3. Nastavte požadované URL udalostí

Vyplňte len URL pre udalosti, ktoré vás zaujímajú. Ostatné nechajte prázdne.

webhook_sign_secretNakonfigurujete zdieľané tajomstvo na stránke nastavení. Každý odchádzajúci webhook sa ním podpíše. Váš príjemca prepočíta podpis a porovná — ak sa zhodujú, payload je pravý a nezmenený.
order_create_webhook_urlSpustí sa pri vytvorení objednávky lokálneho doručenia (Delivery / Pickup / P2P) akoukoľvek cestou: web formulár, REST/GraphQL API, synchronizácia e-commerce platformy, automatické pravidlá, importované riadky atď. Vylučuje label-service a iné nedoručovacie typy objednávok. Preskočené v batch toku, ak má rovnaký príjemca tiež nakonfigurovaný order_create_async_postback_url. Konfigurujte cez order_create_webhook_url.
order_status_change_webhook_urlSpustí sa pri každej zmene stavu — vyzdvihnuté, v tranzite, doručené, výnimka, zrušené. Konfigurujte cez order_status_change_webhook_url.
tracking_event_webhook_urlSpustí sa pri každej udalosti životného cyklu sledovania balíka. Konfigurujte cez tracking_event_webhook_url. Udalosti doručenia a vyzdvihnutia obsahujú aj doklad o doručení: proof_files a proof_files_detail (file_id, type, url, full_url, podpísaná URL na stiahnutie). Fotografie nahraté po udalosti prichádzajú ako pod.files_updated. Každý súbor nesie aj kontext svojej udalosti: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) a service_status (1 = success / 2 = failed); pri starých súboroch bez zaznamenanej udalosti sú null.
order_create_async_postback_urlSpustí sa raz po dokončení spracovania dávkového importu. Payload obsahuje pole výsledkov na riadok. Konfigurujte cez order_create_async_postback_url.
pod_files_webhook_urlSpustí sa, keď sa fotografia doručenia alebo podpis pridá, nahradí alebo odstráni (action: added / updated / removed) — jedno doručenie na súbor, už žiadne dopytovanie príloh. Aktivuje sa nastavením pod_files_webhook_url. Každý súbor nesie aj kontext svojej udalosti: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) a service_status (1 = success / 2 = failed); pri starých súboroch bez zaznamenanej udalosti sú null.
order_deleted_webhook_urlSpustí sa pri trvalom odstránení objednávky, aby ju váš systém mohol zrkadliť. Aktivuje sa nastavením order_deleted_webhook_url.
order_cancel_failed_webhook_urlSpustí sa, keď je pokus o zrušenie zamietnutý (napríklad objednávka je už v doručovaní), aby vaše prevádzkové procesy mohli sledovať neúspešné zrušenia bez dopytovania API. Aktivuje sa nastavením order_cancel_failed_webhook_url.
route_board_webhook_urlSpustí sa, keď miesto na nástenke trás zmení držiteľa alebo sa zmení stav nástenky — pole action hovorí, čo sa stalo (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Iba na úrovni firmy. Prihlásenie cez route_board_webhook_url.
device_order_webhook_urlVoliteľné udalosti pre zásielky spracované vašimi inteligentnými schránkami, kioskmi a smart drop boxmi: zásielka uložená do zariadenia, vyzdvihnutá, vybraná personálom alebo po termíne vyzdvihnutia, ako aj problémy otvorené alebo vyriešené v súvislosti s ňou. Iba rozšírenie — žiadny existujúci webhook sa nemení a nič sa neodošle, kým nenastavíte device_order_webhook_url.
Sprievodca novinkami integrácie

Všetky novinky v API a webhookoch — idempotentné zrušenie, feedy na odsúhlasenie, podpisy v2, nové udalosti — s príkladmi na skopírovanie. Všetko plne spätne kompatibilné.

Podpis a Overenie

Každý odchádzajúci webhook nesie hex-kódovaný HMAC-SHA256 podpis v hlavičke. Príjemca musí prepočítať podpis nad surovým telom so zdieľaným tajomstvom a odmietnuť požiadavku, ak sa nezhoduje.

Algoritmus
HMAC-SHA256 (hex)
Názov hlavičky
Signature
Kroky overenia
  1. Prečítajte surové telo predtým, než ho parsing alebo middleware upravia.
  2. Vypočítajte hash_hmac('sha256', rawBody, sharedSecret) a hex-kódujte.
  3. Porovnajte s hlavičkou Signature v konštantnom čase (hash_equals v PHP, crypto.timingSafeEqual v Node).
  4. Odpovedzte 2xx len ak sa podpisy zhodujú. Inak 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

Opakovania a Spoľahlivosť

Váš endpoint by mal rýchlo odpovedať 2xx. Inak, pri timeoute alebo nedostupnosti, sa doručenie opakuje.

Max. pokusov
5 (počiatočný + 4 opakovania)
Timeout na pokus
3 sekundy
Ústup
Exponenciálne — cca 10s, 100s, 1000s, 10000s
Postavte na idempotenciu. Keďže sa doručenie môže opakovať, príjemca môže vidieť rovnakú udalosť viackrát. Použite ID objednávky/sledovania ako deduplikačný kľúč — uchovajte spracované ID aspoň 24 hodín.
Odporúčaná odpoveď. Rýchlo potvrďte (HTTP 200) a spracujte asynchrónne. Vyhnite sa pomalým operáciám synchrónne v handleri — narazíte na 3-sekundový timeout.

Overovač Podpisu

Vložte prijatý payload, hodnotu hlavičky Signature a vaše tajomstvo — nástroj prepočíta podpis v prehliadači (nič neopúšťa túto stránku) a oznámi, či sa zhodujú.

Poslať Testovací Webhook

Spustite skutočný, správne podpísaný webhook z nášho servera na URL, ktorú zadáte. Použite na testovanie dostupnosti príjemcu, parsovania payload a logiky overenia podpisu.

Posledné Doručenia Webhook

Pozrite si najnovšie pokusy o doručenie webhook na vašom účte — produkčné udalosti aj testy z tejto stránky. Vložte Bearer token na načítanie.

Čas Udalosť URL Stav HTTP Pokus Čas (ms) Testovať? Akcie
Zatiaľ žiadne doručenia webhook.

Najlepšie Postupy

© 2026 superRoute. Centrum pre Vývojárov