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
Ú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