A webhook egy HTTP POST kérés, amelyet a Superroute az Ön által konfigurált URL-re küld, valahányszor történik valami — megrendelés készül, kézbesítés befejeződik, követési esemény rögzítésre kerül. Ön egy fogadó végpontot épít, mi oda kézbesítjük az eseményt.
Hogyan működik a kézbesítés
Az események sorba kerülnek és aszinkron módon küldjük ki. Minden kérés HMAC-SHA256 aláírást hordoz az eredet ellenőrzésére. A sikertelen kézbesítéseket (nem 2xx vagy timeout) exponenciális backoff-fal legfeljebb 5-ször megismételjük.
Biztonsági modell
Ön egy megosztott titkot konfigurál a beállítási oldalon. Minden kimenő webhookot ezzel írunk alá. A fogadó újraszámolja az aláírást és összehasonlítja — ha egyezik, a payload eredeti és sértetlen.
Eseménykatalógus
Nyolc kimenő eseménytípus érhető el. Mindegyiknek saját URL-mezője van a beállítási oldalon — bármilyen részhalmazra feliratkozhat.
megrendelés.létrehozta
Helyi kézbesítési megrendelés (Delivery / Pickup / P2P) létrehozásakor sül el bármilyen úton: web űrlap, REST/GraphQL API, e-commerce platform szinkron, automatikus szabályok, import sorok stb. A label-service és más nem-kézbesítési típusok ki vannak zárva. Batch folyamatban kihagyva, ha ugyanahhoz a címzetthez az order_create_async_postback_url is be van állítva. Állítsa be az order_create_webhook_url segítségével.
A csomag követési életciklusának minden eseményénél elsül. Állítsa be a tracking_event_webhook_url segítségével. A kézbesítési és felvételi események a kézbesítési igazolást is tartalmazzák: proof_files és proof_files_detail (file_id, type, url, full_url, aláírt letöltési URL). Az esemény után feltöltött fényképek pod.files_updated eseményként érkeznek. Minden fájl az eseményének kontextusát is tartalmazza: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) és service_status (1 = success / 2 = failed); rögzített esemény nélküli régi fájloknál null.
Payload Példák
{
"id": 90001,
"order_id": 1001,
"order_ref": "REF-001",
"location_id": 12,
"location_name": "Toronto Depot",
"tracking_event_type": "D",
"tracking_event_status_id": 500,
"tracking_event_key": "deliver_success",
"otep_status": "delivered",
"proof_files": [
"storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg",
"storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg"
],
"proof_files_detail": [
{
"file_id": 234567,
"type": 1,
"url": "storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg",
"full_url": "https://api.superroute.ca/storage/2026-07-20/1001_S_Ab3kQ9xYzLm4Np.jpeg",
"signed_url": "https://api.superroute.ca/files/pod/234567?expires=1784748600&signature=8f2c1d...",
"signed_url_expires_at": 1784748600,
"tracking_event_id": 90001,
"tracking_event_status_id": 500,
"tracking_event_key": "deliver_success",
"service_type": 1,
"service_status": 1
},
{
"file_id": 234568,
"type": 2,
"url": "storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg",
"full_url": "https://api.superroute.ca/storage/2026-07-20/1001_P_Cd7rT2wVuKe8Hs.jpeg",
"signed_url": "https://api.superroute.ca/files/pod/234568?expires=1784748600&signature=41ba90...",
"signed_url_expires_at": 1784748600,
"tracking_event_id": 90001,
"tracking_event_status_id": 500,
"tracking_event_key": "deliver_success",
"service_type": 1,
"service_status": 1
}
],
"description": {
"en": "Your parcel has been delivered successfully. Thank you!",
"fr": "Votre colis a été livré avec succès. Merci !",
"chs": "您的包裹已成功送达，感谢您的使用！",
"cht": "您的包裹已成功送達，感謝您的使用！",
"es": "Tu paquete ha sido entregado con éxito. ¡Gracias!",
"de": "Ihr Paket wurde erfolgreich zugestellt. Vielen Dank!",
"nl": "Uw pakket is succesvol afgeleverd, bedankt voor uw gebruik!",
"pt": "Seu pacote foi entregue com sucesso. Obrigado!",
"it": "Il tuo pacco è stato consegnato con successo. Grazie!",
"sr": "Vaš paket je uspešno dostavljen, hvala vam što koristite naše usluge!",
"hu": "Csomagja sikeresen kiszállításra került, köszönjük hogy használta szolgáltatásunkat!",
"pl": "Twoja paczka została dostarczona pomyślnie. Dziękujemy!",
"sk": "Váš balík bol úspešne doručený. Ďakujeme!",
"cs": "Váš balík byl úspěšně doručen. Děkujeme!"
},
"tracking_number": [
"SR000000001"
],
"external_tracking_number": [
"1Z999AA10123456784"
]
}
order.create_async
Egyszer sül el egy kötegelt import feldolgozás befejezése után. A payload soronkénti eredménytömböt tartalmaz. Állítsa be a order_create_async_postback_url segítségével.
Akkor sül el, ha egy kézbesítési fotót vagy aláírást hozzáadnak, lecserélnek vagy eltávolítanak (action: added / updated / removed) — fájlonként egy kézbesítés, nincs több melléklet-lekérdezés. A pod_files_webhook_url beállításával aktiválható. Minden fájl az eseményének kontextusát is tartalmazza: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) és service_status (1 = success / 2 = failed); rögzített esemény nélküli régi fájloknál null.
Akkor sül el, ha egy rendelést véglegesen törölnek, így a rendszere követni tudja az eltávolítást. Az order_deleted_webhook_url beállításával aktiválható.
Akkor sül el, ha egy lemondási kísérletet elutasítanak (például a rendelés már kiszállítás alatt áll), így az üzemeltetési folyamatai API-lekérdezés nélkül követhetik a sikertelen lemondásokat. Az order_cancel_failed_webhook_url beállításával aktiválható.
Payload Példák
{
"result": false,
"code": "ORDER_ALREADY_IN_DELIVERY",
"message": "Order can no longer be cancelled at its current status",
"http_status": 409,
"submitted": {
"order_id": 1001,
"tracking_number": "SR000000001",
"external_tracking_number": null
}
}
Útvonaltábla-hely megváltozott
Akkor aktiválódik, amikor egy útvonaltábla-hely gazdát cserél vagy a tábla állapota megváltozik — az action mező mondja meg, mi történt (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Csak vállalati szinten. Feliratkozás a route_board_webhook_url mezővel.
Külön webhook-csatorna az okos csomagautomatákkal integrált külső kézbesítési szolgáltatóek számára. Az események a szolgáltatófiókjához beállított végpontra érkeznek, és minden végpont az eseménytípusok tetszőleges részhalmazára iratkozhat fel.
partner_locker.delivery.doors_opened
Ajtók Kinyitva — Abban a pillanatban aktiválódik, amikor a rekeszajtók kinyílnak egy kézbesítési kísérletnél — akár a futár a csomagautomata képernyőjén adta meg a hozzáférési kódot, akár a távoli nyitás API-t használta — beleértve az újrakiosztás miatti újranyitásokat is. Az opening blokk felsorol minden kinyitott rekeszt a grid_id-val, a hardveres ajtószámmal (compartment_number) és a pickup_locker_number-rel (megjelenítési sorszám, oszloponként fentről lefelé, majd balról jobbra számolva). Minden rekesz tartalmazza a pickup_locker_code mezőt is — a "{shelf_code}-{pickup_locker_number}" címkét, amelyhez a címzettet irányítjuk; null, ha a rekesznek nincs átvételi száma. A payload tartalmazza a pickup_code mezőt is — a címzett átvételi kódját, amelyet az ajtók kinyílásának pillanatában osztunk ki; a futár lerakási megerősítése után is ugyanaz a kód marad, átvételre azonban csak a lerakás megerősítése után használható.
Csomagautomatába kézbesítve — Akkor sül el, ha a betárolás megerősítést kapott és a csomagok az automatában vannak. A tartalom a címzett átvételi kódját is tartalmazza. Minden rekesz tartalmazza a pickup_locker_code mezőt is — a "{shelf_code}-{pickup_locker_number}" címkét, amelyhez a címzettet irányítjuk; null, ha a rekesznek nincs átvételi száma. A távoli nyitás API-val nyitott ajtóknál a platform maga zárja le a betárolást, amint az automata minden nyitott ajtót zárva jelent, így az esemény confirm hívás nélkül is elsül; a confirmed_by a lezárás útját nevezi meg: courier_terminal, partner_api, door_close, timeout_door_closed vagy console.
Javító újranyitás — Akkor sül el, ha a foglalt rekeszeket a javítási időablakon belül újranyitják egy téves elhelyezés kijavításához — az automata képernyőjéről vagy az API-n keresztül. A correction blokk felsorolja az újranyitott rekeszeket. Minden rekesz tartalmazza a pickup_locker_code mezőt is — a "{shelf_code}-{pickup_locker_number}" címkét, amelyhez a címzettet irányítjuk; null, ha a rekesznek nincs átvételi száma.
partner_locker_delivery.event_type_code_rotated — Akkor aktiválódik, amikor a partner lecseréli egy kiszállítás kézbesítési vagy átvételi kódját. A rotation blokk megnevezi, melyik kódot cserélték le, mikor, és újraküldték-e a címzett értesítését — az új kód soha nem utazik webhookban; kizárólag a cserélő API közvetlen válaszában jelenik meg.
Aláírás és Ellenőrzés: A szolgáltató csomagautomata-webhookok saját aláírási sémát használnak: az X-Webhook-Signature értéke base64(HMAC-SHA256(titok, időbélyeg + "\n" + kézbesítési azonosító + "\n" + nyers törzs)), ahol az időbélyeg és a kézbesítési azonosító az X-Webhook-Timestamp és X-Webhook-Delivery-Id fejlécekből származik. Ellenőrizze az X-Webhook-Content-Digest fejlécet is (a törzs SHA-256 kivonata), és utasítsa el az elavult időbélyegeket. Az X-Webhook-Id az újrapróbálkozások között változatlan marad — használja idempotenciához.
Hogyan Konfigurálja: A végpontok a Külső kézbesítés → Szolgáltató csomagautomata → Beállítások alatt kezelhetők, szolgáltatóenként egy végpont, választható eseménylistával. A sikertelen kézbesítéseket exponenciális visszavárakozással legfeljebb 7-szer próbálja újra a rendszer, mielőtt holt levélbe kerülnének; a holt levélbe került események az események oldalról kézzel újraküldhetők.
Sandbox (tesztszekrény) események: A tesztszekrényekre létrehozott kézbesítések ugyanazokat a webhook eseményeket bocsátják ki, mint az éles környezet, ugyanazzal a titokkal aláírva, így valósághű forgalommal fejleszthet. A sandbox események háromféleképpen vannak megjelölve: a tartalom "livemode": false értéket hordoz, az event_id PLE-MOCK- előtaggal kezdődik, a kérés pedig tartalmazza az X-Webhook-Test: 1 fejlécet. Ha a végponton be van állítva sandbox URL, a sandbox események oda kerülnek a produkciós URL helyett; egyébként a produkciós URL-re esnek vissza, továbbra is megjelölve. A „Sandbox események kézbesítése" kapcsoló teljesen leállítja a sandbox kézbesítést.
Külső kézbesítési események
A harmadik feles kézbesítési szolgáltatóknak (futároknak) küldött csomagkézbesítési webhookok. A kézbesítési megbízások életciklusát fedik le, így a futárnak többé nem kell lekérdezéssel figyelnie az új munkákat. Ez a kategória elkülönül az alábbi okos csomagautomata eseményektől: minden szolgáltató kategóriánként független végpontot, aláíró titkot és eseményfeliratkozást konfigurál — a saját portálján vagy a platform üzemeltetőjén keresztül.
delivery.assignment.created
Megbízás létrehozva — Akkor aktiválódik, amikor egy megrendelést a szolgáltatóhoz rendelnek — automatikus szabállyal vagy kézzel. A payload tartalmazza a megbízás számát, a megrendelés-azonosítókat és a csomagok követési számait.
Megbízás törölve — Akkor aktiválódik, amikor a platform visszavon egy megbízást a szolgáltatótól. A reason mező megkülönbözteti: cancelled (a megbízást törölték a fuvarozónál), fallback_to_self_delivery (a platform visszavette a megrendelést saját kézbesítésbe) és reassigned (a megrendelést másik szolgáltatóhoz helyezték át).
Részleges kézbesítés — Akkor indul, ha a küldemény egy részét kézbesítették, míg a többi csomag még úton van. A packages tömb csomagonként tartalmazza az eredményt, a legs pedig a fuvarozónál rögzített külső rendeléseket sorolja fel — csomagonként egyet, ha a fuvarozó nem fogad többdarabos küldeményt.
Aláírás és Ellenőrzés: A külső kézbesítési webhookok ugyanazt az aláírási sémát használják, mint a szolgáltató csomagautomata webhookok: az X-Webhook-Signature értéke base64(HMAC-SHA256(secret, timestamp + "\n" + delivery id + "\n" + raw body)), ahol a timestamp és a delivery id az X-Webhook-Timestamp és X-Webhook-Delivery-Id fejlécekből származik. Ellenőrizze az X-Webhook-Content-Digest fejlécet is (a törzs SHA-256 kivonata), és utasítsa el az elavult időbélyegeket. Az X-Webhook-Id az újrapróbálkozások során változatlan marad — használja idempotenciához.
Hogyan Konfigurálja: A szolgáltatók ezt a végpontot maguk konfigurálják a szolgáltatói portálon (Webhook beállítások), vagy a platform üzemeltetője teszi meg a Külső kézbesítés → Szolgáltatók → Webhooks alatt. Szolgáltatónként egy végpont, választható eseménylistával. Az aláíró titok automatikusan generálható vagy egyéni értékre állítható, és a beállítások oldalon megtekinthető. A sikertelen kézbesítéseket exponenciális visszavárakozással legfeljebb 7-szer próbálja újra a rendszer, mielőtt holt levélbe kerülnének; a holt levélbe került események kézzel újraküldhetők. A beállítások oldalról bármikor küldhető aláírt teszt (mock) esemény — a tesztkérések az X-Webhook-Test: 1 fejlécet viselik, és a payload adataiban "test": true szerepel.
Rendelés-életciklus események
Részletes, opcionálisan bekapcsolható események a klasszikus order.status_change webhook mellett (amely változatlan marad): ki lett hozzárendelve, elfogadta-e a sofőr, mikor vették fel a csomagot, mikor van úton, mikor kézbesítették vagy hiúsult meg, továbbá a sofőrök szolgálati változásai és a ritkított sofőrpozíciók. Semmi nem kerül elküldésre, amíg be nem állítja az alábbi URL-eket.
order.assigned
Sofőrt rendeltek a rendeléshez (kézzel, útvonaltervezéssel vagy automatikus hozzárendeléssel). data.source = auto_assign, ha az orkesztrátor végezte.
Sofőrpozíció az alkalmazásból vagy a nyomkövetőből, sofőrönként ritkítva a driver_location_min_interval_sec alapján (alapértelmezés 60 s). Csak a driver_location_webhook_url címre kerül elküldésre.
Hogyan Konfigurálja: Beállítások → Webhookok (vagy GET/PUT /api/v1/webhook-settings, GraphQL webhookSettingsUpdate): az order_lifecycle_webhook_url minden order.* eseményt és a driver.on_duty_changed eseményt kapja; az order_lifecycle_events ezt vesszővel elválasztott listára szűkíti; a driver_location_webhook_url és a driver_location_min_interval_sec vezérli a driver.location_update eseményt. Több URL vesszővel elválasztva adható meg. A kézbesítések a webhook kézbesítési naplóban jelennek meg reference_type order / driver értékkel.
Aláírás és Ellenőrzés: Pontosan úgy aláírva, mint fiókja minden más kimenő webhookja: örökölt Signature fejléc, valamint X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 az Ön webhook_sign_secret értékével. Az újrapróbálkozások ugyanazt az event_id értéket használják – ez alapján szűrje ki a duplikátumokat.
Eszközrendelés-események
Opcionális események az okos csomagautomatái, kioszkjai és okos gyűjtődobozai által kezelt csomagokhoz: a csomag bekerült a gépbe, átvették, a személyzet kivette, vagy lejárt az átvételi határideje, valamint a hozzá nyitott vagy lezárt problémák. Kizárólag bővítés — egyetlen meglévő webhook sem változik, és semmi sem kerül kiküldésre, amíg be nem állítja a device_order_webhook_url értéket.
device_order.stored
Egy csomag bekerült a gépbe, és a következő személyre vár (címzett, futár vagy üzemeltető, lásd data.device_order.next_actor). A due_at az átvételi határidő.
A csomag átvétel nélkül túllépte a due_at időpontot. Még a gépben van, és a kódja továbbra is működik; az overdue_at kitöltésre kerül, a next_actor pedig operator lesz.
Probléma nyílt a kezeléshez (például door_left_open, deposit_unverified, item_missing, overdue). A data.exception tartalmazza az id, type, severity és status mezőket.
Payload Példák: 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 (az időpontok ISO 8601 formátumúak, null, amíg nem következnek be). A problémaesemények data.exception mezőt is tartalmaznak: id, type, severity, status, resolution_action. Az átvételi kód soha nem szerepel benne. Az event_id értéke DOE-<naplóesemény-azonosító>, és újrapróbálkozáskor sem változik.
Hogyan Konfigurálja: Beállítások → Webhookok (vagy GET/PUT /api/v1/webhook-settings): a device_order_webhook_url minden device_order.* eseményt megkap; a device_order_events ezt vesszővel elválasztott listára szűkíti. Több URL is megadható vesszővel elválasztva. A kézbesítések a webhook-kézbesítési naplóban jelennek meg reference_type device_order értékkel.
Aláírás és Ellenőrzés: Pontosan úgy aláírva, mint fiókja minden más kimenő webhookja: örökölt Signature fejléc, valamint X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 az Ön webhook_sign_secret értékével. Az újrapróbálkozások ugyanazt az event_id értéket használják – ez alapján szűrje ki a duplikátumokat.
Azokat a csomagokat, amelyeket egy partner fuvarozó a saját fiókjával szállít az Ön automatáiba, ez a csatorna nem küldi el; a partner a saját szolgáltatói csomagautomata-webhookjain keresztül kapja meg őket.
Hogyan Konfigurálja
A webhookokat két szinten konfigurálhatja: vállalkozás szinten (mindenre kiterjed) vagy ügyfelenként (felülírja az adott B2B alfiókhoz).
1. Beállításokhoz
Jelentkezzen be és lépjen a Beállítások → API és Webhookok menüpontba. Az ügyfél-felülírások az ügyfél részletek oldalán találhatók.
2. Aláíró titok beállítása
Válasszon legalább 16 karakter hosszú stringet, ideális esetben 32+ véletlen bájtot. A fogadó ezt használja az aláírás ellenőrzésére.
3. Állítsa be a kívánt esemény URL-eket
Csak azoknak az eseményeknek az URL-jét töltse ki, amelyek érdeklik. A többit hagyja üresen.
webhook_sign_secretÖn egy megosztott titkot konfigurál a beállítási oldalon. Minden kimenő webhookot ezzel írunk alá. A fogadó újraszámolja az aláírást és összehasonlítja — ha egyezik, a payload eredeti és sértetlen.
order_create_webhook_urlHelyi kézbesítési megrendelés (Delivery / Pickup / P2P) létrehozásakor sül el bármilyen úton: web űrlap, REST/GraphQL API, e-commerce platform szinkron, automatikus szabályok, import sorok stb. A label-service és más nem-kézbesítési típusok ki vannak zárva. Batch folyamatban kihagyva, ha ugyanahhoz a címzetthez az order_create_async_postback_url is be van állítva. Állítsa be az order_create_webhook_url segítségével.
order_status_change_webhook_urlMinden állapotátmenetnél elsül — felvéve, úton, kézbesítve, kivétel, törölve. Állítsa be a order_status_change_webhook_url segítségével.
tracking_event_webhook_urlA csomag követési életciklusának minden eseményénél elsül. Állítsa be a tracking_event_webhook_url segítségével. A kézbesítési és felvételi események a kézbesítési igazolást is tartalmazzák: proof_files és proof_files_detail (file_id, type, url, full_url, aláírt letöltési URL). Az esemény után feltöltött fényképek pod.files_updated eseményként érkeznek. Minden fájl az eseményének kontextusát is tartalmazza: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) és service_status (1 = success / 2 = failed); rögzített esemény nélküli régi fájloknál null.
order_create_async_postback_urlEgyszer sül el egy kötegelt import feldolgozás befejezése után. A payload soronkénti eredménytömböt tartalmaz. Állítsa be a order_create_async_postback_url segítségével.
pod_files_webhook_urlAkkor sül el, ha egy kézbesítési fotót vagy aláírást hozzáadnak, lecserélnek vagy eltávolítanak (action: added / updated / removed) — fájlonként egy kézbesítés, nincs több melléklet-lekérdezés. A pod_files_webhook_url beállításával aktiválható. Minden fájl az eseményének kontextusát is tartalmazza: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) és service_status (1 = success / 2 = failed); rögzített esemény nélküli régi fájloknál null.
order_deleted_webhook_urlAkkor sül el, ha egy rendelést véglegesen törölnek, így a rendszere követni tudja az eltávolítást. Az order_deleted_webhook_url beállításával aktiválható.
order_cancel_failed_webhook_urlAkkor sül el, ha egy lemondási kísérletet elutasítanak (például a rendelés már kiszállítás alatt áll), így az üzemeltetési folyamatai API-lekérdezés nélkül követhetik a sikertelen lemondásokat. Az order_cancel_failed_webhook_url beállításával aktiválható.
route_board_webhook_urlAkkor aktiválódik, amikor egy útvonaltábla-hely gazdát cserél vagy a tábla állapota megváltozik — az action mező mondja meg, mi történt (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Csak vállalati szinten. Feliratkozás a route_board_webhook_url mezővel.
device_order_webhook_urlOpcionális események az okos csomagautomatái, kioszkjai és okos gyűjtődobozai által kezelt csomagokhoz: a csomag bekerült a gépbe, átvették, a személyzet kivette, vagy lejárt az átvételi határideje, valamint a hozzá nyitott vagy lezárt problémák. Kizárólag bővítés — egyetlen meglévő webhook sem változik, és semmi sem kerül kiküldésre, amíg be nem állítja a device_order_webhook_url értéket.
Minden kimenő webhook hex-kódolt HMAC-SHA256 aláírást tartalmaz a fejlécben. A fogadónak újra ki kell számolnia az aláírást a nyers törzs felett a megosztott titokkal, és el kell utasítania a kérést, ha nem egyezik.
Algoritmus
HMAC-SHA256 (hex)
Fejléc neve
Signature
Ellenőrzési lépések
Olvassa be a nyers törzset, mielőtt a parsing vagy middleware módosítja.
Számítsa hash_hmac('sha256', rawBody, sharedSecret), majd hex-kódolja.
Hasonlítsa össze a Signature fejléccel konstans idejű hasonlítással (hash_equals PHP-ben, crypto.timingSafeEqual Node-ban).
2xx csak akkor, ha az aláírások egyeznek. Egyébként 401.
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
Árak elrejtése
Szolgáltatója rendeléstípusonként (Helyi Kézbesítés, Címke szolgáltatás, Szállítási szolgáltatás, LTL szolgáltatás, Tárolási szolgáltatások, Költöztetési szolgáltatások, eszközrendelések) elrejtheti árait egy ügyfélfiók elől. Ha ez Önre vonatkozik, a végpontjára érkező kézbesítések nem tartalmaznak ármezőket: a shipping_price, price_details, currency, adó, pótdíjösszegek, díjszabási árak és hasonlók kimaradnak, nem nullaként érkeznek. A díjszabási listák megtartják a rate_id-t és a szolgáltatásneveket, hogy továbbra is választható legyen szolgáltatás.
Semmi más nem változik. Az eseménytípusok, minden más mező, az aláírás és az újrapróbálási szabályok pontosan a dokumentáltak. Az ármezőket tekintse opcionálisnak, és soha ne feltételezze, hogy a hiányzó összeg ingyenest jelent.
Újrapróbálkozás és Megbízhatóság
A végpontnak gyorsan 2xx-szel kell válaszolnia. Egyébként, timeout vagy elérhetetlenség esetén a kézbesítés ismétlődik.
Max. próbálkozás
5 (kezdeti + 4 ismétlés)
Timeout próbálkozásonként
3 másodperc
Visszalépés
Exponenciális — kb. 10s, 100s, 1000s, 10000s
Tervezzen idempotensen. Mivel a kézbesítés megismétlődhet, a fogadó ugyanazt az eseményt többször is láthatja. Használja a megrendelés/követés ID-t deduplikációs kulcsként — tárolja a feldolgozott ID-ket legalább 24 óráig.
Ajánlott válasz. Gyors visszaigazolás (HTTP 200), majd aszinkron feldolgozás. Kerülje a lassú szinkron műveleteket a handler-ben — a 3 másodperces timeout-ba ütközik.
Aláírás Ellenőrző
Másoljon be egy beérkezett payload-ot, a Signature fejléc értékét és a titkát — az eszköz a böngészőben újraszámolja az aláírást (semmi nem hagyja el ezt az oldalt), és jelzi, hogy egyezik-e.
Teszt Webhook Küldése
Indítson egy valódi, megfelelően aláírt webhookot a szerverünkről egy Ön által megadott URL-re. Hasznos a fogadó elérhetőségének, a payload parsing-nak és az aláírás-ellenőrző logikának a teszteléséhez.
Legutóbbi Webhook Kézbesítések
Tekintse meg a legutóbbi webhook kézbesítési kísérleteket a fiókján — valós produkciós eseményeket és erről az oldalról küldött teszteket. Bearer token beillesztése a betöltéshez.
Idő
Esemény
URL
Státusz
HTTP
Próbálkozás
Idő (ms)
Teszt?
Műveletek
Még nincs webhook kézbesítés.
Legjobb Gyakorlatok
Gyors visszaigazolás (HTTP 200), majd aszinkron feldolgozás a 3 másodperces timeout elkerülése érdekében.
Mindig ellenőrizze az aláírást, mielőtt megbízna a payload-ban.
Kezelje az eseményeket at-least-once módon — deduplikáljon megrendelés/követés szám alapján.
WEBHOOKS