WEBHOOKS
Webhook-ovi
Primajte događaje u realnom vremenu od Superroute-a — porudžbine, promene statusa, ažuriranja praćenja. Sa potpisanim payload-ima, automatskim ponavljanjima i ugrađenim debugerom.
WEBHOOKS
Primajte događaje u realnom vremenu od Superroute-a — porudžbine, promene statusa, ažuriranja praćenja. Sa potpisanim payload-ima, automatskim ponavljanjima i ugrađenim debugerom.
Webhook je HTTP POST zahtev koji Superroute šalje na URL koji ste konfigurisali kad god se nešto desi — porudžbina se kreira, isporuka završi, događaj praćenja zabeleži. Vi pravite prijemnu tačku, mi tu isporučujemo događaj.
Događaji se stavljaju u red i šalju asinhrono. Svaki zahtev nosi HMAC-SHA256 potpis za verifikaciju porekla. Neuspele isporuke (ne-2xx ili timeout) se ponavljaju sa eksponencijalnim backoff-om do 5 puta.
Vi konfigurišete deljenu tajnu na stranici podešavanja. Svaki odlazni webhook se potpisuje tom tajnom. Vaš prijemnik ponovo izračunava potpis i upoređuje — ako se poklope, payload je autentičan i nepromenjen.
Dostupno je osam tipova odlaznih događaja. Svaki ima svoj URL na stranici podešavanja — pretplatite se na bilo koji podskup.
Mašinski čitljiv opis svih odlaznih događaja, sa šemama sadržaja, zaglavljima i rasporedima ponovnih pokušaja (AsyncAPI 3.0): asyncapi-webhooks.json
Okida se pri kreiranju lokalne dostave (Delivery / Pickup / P2P) bilo kojim putem — web forma, REST/GraphQL API, sinhronizacija sa e-commerce platformom, automatska pravila, redovi iz uvoza itd. Isključuje label-service i druge ne-dostavne tipove porudžbina. Preskače se u batch toku kada je za istog primaoca takođe konfigurisan order_create_async_postback_url. Konfigurišite pomoću order_create_webhook_url.
Primeri Payload-aOkida se pri svakoj promeni statusa — preuzeto, u tranzitu, isporučeno, izuzetak, otkazano. Konfigurišite pomoću order_status_change_webhook_url.
Presretanje porudžbine: kada je porudžbina presretnuta, after_status je 48 (Presretnuto), sa operation_type 3043 (back office) ili 6012 (API). Kada se presretanje povuče ili se izvrši ishod, porudžbina napušta 48 sa operation_type 3045 / 6014 ili 3044 / 6013.
Primeri Payload-aOkida se pri svakom događaju životnog ciklusa praćenja paketa. Konfigurišite pomoću tracking_event_webhook_url. Događaji isporuke i preuzimanja nose i dokaz o isporuci: proof_files i proof_files_detail (file_id, type, url, full_url, potpisani URL za preuzimanje). Fotografije otpremljene nakon događaja stižu kao pod.files_updated. Svaki fajl nosi i kontekst svog događaja: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) i service_status (1 = success / 2 = failed); za stare fajlove bez zabeleženog događaja su null.
Primeri Payload-aOkida se jednom nakon obrade serijskog uvoza porudžbina. Payload sadrži niz rezultata po redu. Konfigurišite pomoću order_create_async_postback_url.
Primeri Payload-aOkida se kada se fotografija isporuke ili potpis doda, zameni ili ukloni (action: added / updated / removed) — jedna isporuka po fajlu, bez daljeg anketiranja priloga. Aktivira se podešavanjem pod_files_webhook_url. Svaki fajl nosi i kontekst svog događaja: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) i service_status (1 = success / 2 = failed); za stare fajlove bez zabeleženog događaja su null. Kada zaposleni zameni fotografiju ili potpis, ili postavi arhiviranu verziju kao trenutnu, datoteka se šalje sa action: updated i sadrži samo trenutnu sliku; arhivirane verzije se nikada ne šalju.
Primeri Payload-aOkida se kada se porudžbina trajno obriše, kako bi vaš sistem mogao da preslika uklanjanje. Aktivira se podešavanjem order_deleted_webhook_url.
Primeri Payload-aOkida se kada je pokušaj otkazivanja odbijen (na primer, porudžbina je već u isporuci), kako bi vaši operativni procesi mogli da prate neuspela otkazivanja bez prozivanja API-ja. Aktivira se podešavanjem order_cancel_failed_webhook_url.
Primeri Payload-aAktivira se kada mesto na tabli ruta promeni vlasnika ili tabla promeni stanje — polje action kaže šta se desilo (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Samo na nivou firme. Pretplata preko route_board_webhook_url.
Primeri Payload-aOdvojen webhook kanal za spoljne dobavljače za isporuku integrisane sa pametnim ormarićima. Događaji se isporučuju na krajnju tačku podešenu za vaš dobavljačski nalog, a svaka krajnja tačka može da se pretplati na bilo koji podskup tipova događaja.
Vrata Otvorena — Okida se u trenutku kada se vrata pregradaka otvore za pokušaj dostave — bilo da je kurir uneo pristupni kod na ekranu ormarića ili koristio API za daljinsko otvaranje — uključujući ponovna otvaranja zbog preraspodele. Blok opening navodi svaki otvoreni pregradak sa grid_id, hardverskim brojem vrata compartment_number i pickup_locker_number (redni broj za prikaz koji se broji odozgo nadole u svakoj koloni, a zatim sleva nadesno). Svaka pregrada nosi i pickup_locker_code — oznaku "{shelf_code}-{pickup_locker_number}" na koju se upućuje primalac; null kada pregrada nema broj za preuzimanje. Sadržaj poruke uključuje i pickup_code — kôd za preuzimanje primaoca, dodeljen u trenutku otvaranja vrata; ostaje isti kôd nakon što kurir potvrdi ostavljanje pošiljke, a za preuzimanje postaje upotrebljiv tek posle te potvrde.
Primeri Payload-aIsporučeno u paketomat — Okida se kada je odlaganje potvrđeno i paketi su u ormariću. Sadržaj uključuje kôd za preuzimanje primaoca. Svaka pregrada nosi i pickup_locker_code — oznaku "{shelf_code}-{pickup_locker_number}" na koju se upućuje primalac; null kada pregrada nema broj za preuzimanje. Za vrata otvorena putem API-ja za daljinsko otvaranje platforma sama zaključuje odlaganje čim ormarić prijavi da su sva otvorena vrata zatvorena, pa se ovaj događaj okida i bez poziva confirm; confirmed_by označava put zaključenja: courier_terminal, partner_api, door_close, timeout_door_closed ili console.
Primeri Payload-aPreuzeto — Okida se kada primalac preuzme odložene pakete.
Primeri Payload-aIsporuka neuspešna — Okida se kada isporuka ne uspe; uključeni su kodovi grešaka po paketu.
Primeri Payload-aIsteklo — Okida se kada neiskorišćeni kôd za isporuku ili nepreuzeto odlaganje pređe rok važenja.
Primeri Payload-aOtkazano — Okida se kada se isporuka otkaže pre završetka.
Primeri Payload-aPonovno otvaranje radi ispravke — Okida se kada se zauzeti pregradci ponovo otvore u okviru prozora za ispravku radi ispravljanja pogrešnog odlaganja — sa ekrana ormarića ili preko API-ja. Blok correction navodi ponovo otvorene pregradke. Svaka pregrada nosi i pickup_locker_code — oznaku "{shelf_code}-{pickup_locker_number}" na koju se upućuje primalac; null kada pregrada nema broj za preuzimanje.
Primeri Payload-aKod za preuzimanje promenjen — Okida se kada partner zameni kôd za dostavu ili kôd za preuzimanje isporuke. Blok rotation navodi koji je kôd zamenjen, kada i da li je obaveštenje primaocu ponovo poslato — novi kôd nikad ne putuje kroz webhook; otkriva se samo u direktnom odgovoru API-ja za zamenu.
Primeri Payload-aPaket prevoznika distribuiran — Okida se kada se najavljeni paket prevoznika primljen u jednom skladištu stavi na nalog za distribuciju ka lokaciji koju je prevoznik naveo. Blok data nosi broj paketa, referencu prevoznika i članski broj, nalog za distribuciju (order_id, order_ref, status) i polaznu i odredišnu lokaciju. Beleži se samo za prevoznike sa nalogom dobavljača.
Primeri Payload-aPaket prevoznika utovaren — Okida se kada se paket skenira u kamion u polaznom skladištu; distribution.status je in_transit, a loaded_at je postavljen.
Primeri Payload-aPaket prevoznika isporučen na lokaciju — Okida se kada vozač preda nalog za distribuciju na lokaciji; distribution.status je delivered, a delivered_at je postavljen. Uskladištenje je kasniji, zaseban događaj.
Primeri Payload-aPaket prevoznika uskladišten na lokaciji — Okida se kada se paket uskladišti na lokaciji, u pregradu ormarića ili na policu; location nosi grid_id, grid_code i shelf_code. Obaveštenje primaocu o preuzimanju šalje se u tom trenutku.
Primeri Payload-aPaket prevoznika uklonjen iz distribucije — Okida se kada se paket ukloni sa naloga za distribuciju pre polaska ili se nalog otkaže; distribution.reason je removed ili cancelled. Paket se vraća na listu za distribuciju skladišta.
Primeri Payload-aPotpis i Verifikacija: Webhook-ovi dobavljačskih ormarića koriste sopstvenu šemu potpisivanja: X-Webhook-Signature je base64(HMAC-SHA256(tajna, vremenska oznaka + "\n" + id isporuke + "\n" + sirovo telo)), pri čemu vremenska oznaka i id isporuke dolaze iz zaglavlja X-Webhook-Timestamp i X-Webhook-Delivery-Id. Proverite i X-Webhook-Content-Digest (SHA-256 tela) i odbijte zastarele vremenske oznake. X-Webhook-Id ostaje stabilan kroz ponovne pokušaje — koristite ga za idempotentnost.
Kako Konfigurisati: Krajnje tačke se upravljaju u Isporuka trećih strana → Dobavljačski ormarić → Podešavanja, jedna krajnja tačka po dobavljaču, sa listom događaja koja se bira. Neuspele isporuke se ponavljaju uz eksponencijalno odlaganje do 7 puta pre slanja u mrtvo pismo; događaji iz mrtvog pisma mogu se ručno ponovo poslati sa stranice događaja.
Sandbox događaji (probni ormarići): Isporuke kreirane na probnim ormarićima emituju iste webhook događaje kao produkcija, potpisane istim tajnim ključem, tako da možete razvijati uz realističan saobraćaj. Sandbox događaji su označeni na tri načina: sadržaj nosi "livemode": false, event_id počinje sa PLE-MOCK-, a zahtev sadrži zaglavlje X-Webhook-Test: 1. Ako je na krajnjoj tački podešena sandbox adresa, sandbox događaji idu tamo umesto na produkcijsku adresu; u suprotnom se vraćaju na produkcijsku adresu, i dalje označeni. Prekidač „Isporučuj sandbox događaje" potpuno zaustavlja sandbox isporuku.
Webhook-ovi za dostavu paketa koji se šalju dobavljačima dostave preko trećih strana (kuririma). Pokrivaju životni ciklus dodela dostave, tako da kurir više ne mora da proverava nove poslove upitima. Ova kategorija je odvojena od Smart Locker događaja ispod: svaki dobavljač konfiguriše nezavisnu krajnju tačku, tajni ključ za potpisivanje i pretplatu na događaje po kategoriji — u sopstvenom portalu ili preko operatera platforme.
Dodela kreirana — Aktivira se kada je porudžbina dodeljena dobavljaču — automatskim pravilom ili ručno. Sadržaj nosi broj dodele, identifikatore porudžbine i brojeve za praćenje paketa.
Primeri Payload-aPaketi predati — Aktivira se kada je magacin fizički predao sve pakete dodele dobavljaču.
Primeri Payload-aDodela otkazana — Aktivira se kada platforma povuče dodelu od dobavljača. Polje reason razlikuje cancelled (dodela je otkazana kod prevoznika), fallback_to_self_delivery (platforma je vratila porudžbinu na sopstvenu dostavu) i reassigned (porudžbina je premeštena drugom dobavljaču).
Primeri Payload-aDelimična isporuka — Aktivira se kada je deo pošiljke isporučen, dok su ostali paketi još u toku. Niz packages sadrži ishod svakog paketa, a legs navodi spoljne porudžbine kreirane kod prevoznika — po jednu za svaki paket kada prevoznik ne prima pošiljke sa više paketa.
Primeri Payload-aPotpis i Verifikacija: Webhook-ovi isporuke trećih strana koriste istu šemu potpisivanja kao webhook-ovi dobavljačskih ormarića: X-Webhook-Signature je base64(HMAC-SHA256(secret, timestamp + "\n" + delivery id + "\n" + raw body)), pri čemu se timestamp i delivery id uzimaju iz zaglavlja X-Webhook-Timestamp i X-Webhook-Delivery-Id. Proverite i X-Webhook-Content-Digest (SHA-256 tela) i odbacite zastarele vremenske oznake. X-Webhook-Id ostaje stabilan kroz ponovne pokušaje — koristite ga za idempotentnost.
Kako Konfigurisati: Dobavljači sami konfigurišu ovu krajnju tačku u portalu dobavljača (Webhook podešavanja), ili to čini operater platforme u Isporuka trećih strana → Dobavljači → Webhooks. Jedna krajnja tačka po dobavljaču sa listom događaja koja se bira. Tajni ključ za potpisivanje može se automatski generisati ili podesiti na prilagođenu vrednost, i može se pogledati na stranici podešavanja. Neuspele isporuke se ponavljaju uz eksponencijalno odlaganje do 7 puta pre slanja u mrtvo pismo; događaji iz mrtvog pisma mogu se ručno ponovo poslati. Potpisan test (mock) događaj može se poslati u bilo kom trenutku sa stranice podešavanja — test zahtevi nose zaglavlje X-Webhook-Test: 1 i sadrže "test": true u podacima payload-a.
Potpisani push-evi o predajama razmenjenim preko Open Order Handoff Protocol-a: promene životnog ciklusa (prihvaćena, odbijena, istekla, otkazana), odgovori na izmene, događaji praćenja i nove stavke obračuna. Pretplata po OHP tokenu preko POST /api/v1/ohp/subscriptions; endpoint mora prvo vratiti izazov da bi pretplata postojala. Svaki sadržaj je OHP koverta; message_id ostaje isti pri svakom ponovnom pokušaju — deduplikujte po njemu. Pull ostaje izvor istine.
Potpis i Verifikacija: X-Ohp-Signature: v1= + heksadecimalni HMAC-SHA256 od "{timestamp}.{raw body}" sa tajnom pretplate. X-Ohp-Timestamp se menja po pokušaju; X-Ohp-Delivery je jednak message_id. CloudEvents i Standard Webhooks dostupni su po pretplati.
Kako Konfigurisati: Upravlja se OHP tokenom: POST /api/v1/ohp/subscriptions (url, secret, events, format, signature), GET za listanje, DELETE za opoziv. Mašinski čitljiv katalog navodi svaki događaj pod pošiljaocem ohp.
Detaljni, opcioni događaji pored klasičnog order.status_change webhook-a (koji ostaje nepromenjen): ko je dodeljen, da li je vozač prihvatio, kada je paket preuzet, na putu, isporučen ili neuspešan, uz promene smene vozača i pozicije vozača sa ograničenom učestalošću. Ništa se ne šalje dok ne podesite URL-ove ispod.
Porudžbini je dodeljen vozač (ručno, planiranjem ruta ili automatskom dodelom). data.source = auto_assign kada je to uradio orkestrator.
Primeri Payload-aPorudžbina je izgubila vozača (predaja, opoziv, odbijanje, istek vremena). data.previous_driver_id pokazuje ko ju je imao.
Primeri Payload-aVozač je u aplikaciji prihvatio automatski dodeljenu porudžbinu (smena vozača sa obaveznim prihvatanjem).
Primeri Payload-aVozač je odbio dodeljenu porudžbinu; data.reason nosi opcioni razlog u slobodnom tekstu.
Primeri Payload-aVozač je započeo preuzimanje (status Preuzimanje započeto / Na preuzimanju).
Primeri Payload-aPaket je preuzet (status Već preuzeto).
Primeri Payload-aPaket je na putu ka primaocu (status Dostava započeta / U dostavi).
Primeri Payload-aDostava je uspela (status Uspešno).
Primeri Payload-aPokušaj dostave nije uspeo (Ponovo dostaviti kasnije, Potrebno ponovno planiranje, Odbio primalac).
Primeri Payload-aPorudžbina je otkazana.
Primeri Payload-aOsoblje (ili vozač, kada je dozvoljeno) je označilo porudžbinu kao spremnu za preuzimanje (Opcije dispečinga → spremno za preuzimanje).
Primeri Payload-aVozač je u aplikaciji započeo ili završio smenu (opcija smene vozača).
Primeri Payload-aPozicija vozača iz aplikacije ili trekera, ograničena po vozaču pomoću driver_location_min_interval_sec (podrazumevano 60 s). Šalje se samo na driver_location_webhook_url.
Primeri Payload-aKako Konfigurisati: Podešavanja → Webhook-ovi (ili GET/PUT /api/v1/webhook-settings, GraphQL webhookSettingsUpdate): order_lifecycle_webhook_url prima svaki order.* događaj i driver.on_duty_changed; order_lifecycle_events sužava to na listu razdvojenu zarezima; driver_location_webhook_url i driver_location_min_interval_sec kontrolišu driver.location_update. Više URL-ova može biti razdvojeno zarezima. Isporuke se prikazuju u dnevniku isporuke webhook-ova sa reference_type order / driver.
Potpis i Verifikacija: Potpisano tačno kao i svaki drugi odlazni webhook vašeg naloga: nasleđeno Signature zaglavlje plus X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 sa vašim webhook_sign_secret. Ponovni pokušaji koriste isti event_id – deduplikujte po njemu.
Opcioni događaji za pakete kojima rukuju vaši pametni ormarići, kiosci i pametni sandučići: paket smešten u uređaj, preuzet, izvađen od strane osoblja ili sa isteklim rokom za preuzimanje, kao i problemi otvoreni ili rešeni u vezi sa njim. Isključivo dopuna — nijedan postojeći webhook se ne menja i ništa se ne šalje dok ne podesite device_order_webhook_url.
Paket je smešten u uređaj i čeka sledeću osobu (primaoca, kurira ili operatera, pogledajte data.device_order.next_actor). due_at je rok za preuzimanje.
Primeri Payload-aPaket je preuzela osoba koju je čekao — primalac, kurir ili osoblje koje prazni pametni sandučić.
Primeri Payload-aOsoblje je izvadilo paket iz uređaja. removal_reason navodi razlog: overdue_return, handover, relay, anomaly, recovery, pending_area, deleted ili destroyed.
Primeri Payload-aPaket je prekoračio due_at bez preuzimanja. Još uvek je u uređaju i njegov kod i dalje radi; postavlja se overdue_at, a next_actor postaje operator.
Primeri Payload-aOtvoren je problem u vezi sa rukovanjem (na primer door_left_open, deposit_unverified, item_missing, overdue). data.exception sadrži id, type, severity i status.
Primeri Payload-aNeko je zatvorio problem u vezi sa rukovanjem. data.exception.status je resolved ili dismissed, a resolution_action navodi šta je urađeno.
Primeri Payload-aPrimeri Payload-a: 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 (vremena u formatu ISO 8601, null dok ne nastupe). Događaji problema dodaju data.exception: id, type, severity, status, resolution_action. Kod za preuzimanje nikada nije uključen. event_id ima oblik DOE-<id događaja iz registra> i ostaje isti pri ponovnim pokušajima.
Kako Konfigurisati: Podešavanja → Webhooks (ili GET/PUT /api/v1/webhook-settings): device_order_webhook_url prima svaki device_order.* događaj; device_order_events to sužava na listu razdvojenu zarezima. Više URL adresa može se razdvojiti zarezima. Isporuke se prikazuju u dnevniku isporuka webhookova sa reference_type device_order.
Potpis i Verifikacija: Potpisano tačno kao i svaki drugi odlazni webhook vašeg naloga: nasleđeno Signature zaglavlje plus X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 sa vašim webhook_sign_secret. Ponovni pokušaji koriste isti event_id – deduplikujte po njemu.
Paketi koje partnerski prevoznik isporuči u vaše ormariće pod sopstvenim nalogom ne šalju se ovim kanalom; partner ih prima putem sopstvenih webhookova ormarića dobavljača.
Webhook-ove možete konfigurisati na dva nivoa: na nivou kompanije (pokriva sve) ili po klijentu (preglašava za taj specifični B2B podnaloga).
Prijavite se i idite na Podešavanja → API i Webhook-ovi. Preglašavanja po klijentu su na stranici detalja klijenta.
Odaberite string od najmanje 16 karaktera, idealno 32+ slučajnih bajtova. Vaš prijemnik koristi ovu tajnu za verifikaciju potpisa.
Popunite samo URL-ove za događaje koji vam trebaju. Ostalo ostavite prazno.
вебхоок_сигн_сецретVi konfigurišete deljenu tajnu na stranici podešavanja. Svaki odlazni webhook se potpisuje tom tajnom. Vaš prijemnik ponovo izračunava potpis i upoređuje — ako se poklope, payload je autentičan i nepromenjen.ордер_цреате_вебхоок_урлOkida se pri kreiranju lokalne dostave (Delivery / Pickup / P2P) bilo kojim putem — web forma, REST/GraphQL API, sinhronizacija sa e-commerce platformom, automatska pravila, redovi iz uvoza itd. Isključuje label-service i druge ne-dostavne tipove porudžbina. Preskače se u batch toku kada je za istog primaoca takođe konfigurisan order_create_async_postback_url. Konfigurišite pomoću order_create_webhook_url.ордер_статус_цханге_вебхоок_урлOkida se pri svakoj promeni statusa — preuzeto, u tranzitu, isporučeno, izuzetak, otkazano. Konfigurišite pomoću order_status_change_webhook_url.трацкинг_евент_вебхоок_урлOkida se pri svakom događaju životnog ciklusa praćenja paketa. Konfigurišite pomoću tracking_event_webhook_url. Događaji isporuke i preuzimanja nose i dokaz o isporuci: proof_files i proof_files_detail (file_id, type, url, full_url, potpisani URL za preuzimanje). Fotografije otpremljene nakon događaja stižu kao pod.files_updated. Svaki fajl nosi i kontekst svog događaja: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) i service_status (1 = success / 2 = failed); za stare fajlove bez zabeleženog događaja su null.ордер_цреате_асинц_постбацк_урлOkida se jednom nakon obrade serijskog uvoza porudžbina. Payload sadrži niz rezultata po redu. Konfigurišite pomoću order_create_async_postback_url.pod_files_webhook_urlOkida se kada se fotografija isporuke ili potpis doda, zameni ili ukloni (action: added / updated / removed) — jedna isporuka po fajlu, bez daljeg anketiranja priloga. Aktivira se podešavanjem pod_files_webhook_url. Svaki fajl nosi i kontekst svog događaja: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) i service_status (1 = success / 2 = failed); za stare fajlove bez zabeleženog događaja su null. Kada zaposleni zameni fotografiju ili potpis, ili postavi arhiviranu verziju kao trenutnu, datoteka se šalje sa action: updated i sadrži samo trenutnu sliku; arhivirane verzije se nikada ne šalju.order_deleted_webhook_urlOkida se kada se porudžbina trajno obriše, kako bi vaš sistem mogao da preslika uklanjanje. Aktivira se podešavanjem order_deleted_webhook_url.order_cancel_failed_webhook_urlOkida se kada je pokušaj otkazivanja odbijen (na primer, porudžbina je već u isporuci), kako bi vaši operativni procesi mogli da prate neuspela otkazivanja bez prozivanja API-ja. Aktivira se podešavanjem order_cancel_failed_webhook_url.route_board_webhook_urlAktivira se kada mesto na tabli ruta promeni vlasnika ili tabla promeni stanje — polje action kaže šta se desilo (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Samo na nivou firme. Pretplata preko route_board_webhook_url.device_order_webhook_urlOpcioni događaji za pakete kojima rukuju vaši pametni ormarići, kiosci i pametni sandučići: paket smešten u uređaj, preuzet, izvađen od strane osoblja ili sa isteklim rokom za preuzimanje, kao i problemi otvoreni ili rešeni u vezi sa njim. Isključivo dopuna — nijedan postojeći webhook se ne menja i ništa se ne šalje dok ne podesite device_order_webhook_url.order_intercept_webhook_urlOpcioni događaji presretanja porudžbina: zatraženo, na snazi, paket zadržan u magacinu, ishod izvršen, povučeno, odbijeno ili neuspelo. Kupci mogu da ga podese za svoje porudžbine. Samo dodatak — nijedan postojeći webhook se ne menja i ništa se ne šalje dok se ne podesi order_intercept_webhook_url.Sve novine u API-ju i webhook-ovima — idempotentno otkazivanje, feed-ovi za usaglašavanje, v2 potpisi, novi događaji — sa primerima za kopiranje. Sve potpuno unazad kompatibilno.
Svaki odlazni webhook nosi hex-kodiran HMAC-SHA256 potpis u zaglavlju. Vaš prijemnik mora ponovo izračunati potpis nad sirovim telom koristeći deljenu tajnu i odbiti zahtev ako se ne poklope.
Svaka webhook adresa može da prima događaje u izvornom formatu ili kao CloudEvents, a može da dobija i Standard Webhooks zaglavlja za potpis. Podešava se za svaku adresu u webhook podešavanjima. Adresa bez podešavanja prima događaje tačno kao do sada.
native — JSON telo i zaglavlja opisani na ovoj stranici.ce_binary — Isto telo; CloudEvents atributi se šalju kao ce-* zaglavlja.ce_structured — Telo je CloudEvent (Content-Type: application/cloudevents+json) sa izvornim telom u data. Isto je pri svakom ponovnom pokušaju i izvorni potpisi ga pokrivaju.ce-id i webhook-id nose sopstveni event_id događaja kada ga telo ima, inače X-Webhook-Event-Id. Sam X-Webhook-Event-Id se ne menja. ce-source i ce-srbusiness označavaju preduzeće, i kod isporuka njegovim klijentima.
Webhookovi za isporuke u ormariće partnera i isporuku treće strane nude isti izbor po endpointu, na stranici webhook podešavanja dobavljača. Povratni pozivi planova utovara i Open Platform dobijaju ga po zahtevu: callback_format i callback_signature, odnosno callback.format i callback.signature. Za njih su ce-id i webhook-id sopstveni identifikator događaja (X-Webhook-Id, X-Webhook-Event-Id ili X-Open-Delivery), ce-source označava preduzeće koje šalje, a 24 sata posle rotacije ključa dobavljača webhook-signature sadrži po jedan potpis za svaki ključ.
Webhookovi skupova podataka nude isti izbor po webhooku, u obrascu webhooka i u njegovom API-ju (event_format i standard_signature). Standard Webhooks koristi tajni ključ webhooka, pa je on potreban. URL-ovi webhookova skupova podataka moraju biti javne HTTPS adrese.
Uz Standard Webhooks svaka isporuka nosi i webhook-id, webhook-timestamp i webhook-signature. Ponovo se potpisuju pri svakom ponovnom pokušaju, pa je i ponovni pokušaj u toleranciji od 5 minuta. Ključ je vaš webhook ključ za potpis u whsec_ obliku, prikazan na stranici podešavanja. Izvorna zaglavlja se i dalje šalju.
Svaki pošiljalac potpisuje drugačije. Naziv zaglavlja X-Webhook-Signature koriste tri pošiljaoca sa tri različita postupka; proverite postupkom pošiljaoca koji vas je pozvao.
| Pošiljalac | Zaglavlja | Potpis |
|---|---|---|
| Webhookovi zakupca (ova stranica) | Content-Type, Signature, X-Webhook-Event-Id, X-Webhook-Timestamp, X-Webhook-Signature-V2 |
Signature = hex(HMAC-SHA256(body))
X-Webhook-Signature-V2 = hex(HMAC-SHA256(timestamp + "." + body)) |
| Isporuke u ormariće partnera | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature, X-Webhook-Test |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Dodele isporuci treće strane | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Povratni pozivi planova utovara | Content-Type, X-Webhook-Event-Id, X-Webhook-Event-Type, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| Povratni pozivi poslova Open Platform | Content-Type, X-Open-Event, X-Open-Delivery, X-Open-Job, X-Open-Timestamp, X-Open-Signature |
X-Open-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| OHP push | Content-Type, X-Ohp-Event, X-Ohp-Delivery, X-Ohp-Timestamp, X-Ohp-Signature |
|
| Webhookovi skupova podataka | Content-Type, X-Webhook-Event, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = hex(HMAC-SHA256(body)) |
| Webhookovi zakupca sa Standard Webhooks | webhook-id, webhook-timestamp, webhook-signature |
webhook-signature = "v1," + base64(HMAC-SHA256(webhook-id + "." + webhook-timestamp + "." + body)) |
Vaš pružalac usluga može da sakrije svoje cene od naloga kupca, po vrsti porudžbine (Lokalna dostava, Usluga nalepnica, Usluga dostave, LTL usluga, Usluge skladištenja, Usluge selidbe, porudžbine uređaja). Kada se to odnosi na vas, isporuke na vaš endpoint ne sadrže polja cene: shipping_price, price_details, currency, porez, iznosi doplata, cene tarifa i slično se izostavljaju umesto da se šalju kao nula. Liste tarifa zadržavaju rate_id i nazive usluga da bi usluga i dalje mogla da se izabere.
Isporuka na nalog kupca opisuje pošiljku na isti način, bez obzira na to ko je prevozi. Za pošiljku koju prevozi drugi prevoznik: order.status_change šalje tipove operacija 6007, 2009, 6008, 6009 i 6010 kao 1001, 2002 ili 6002, sa praznim operation_description i ip_address; statusi 33 i 43 šalju se kao 29 i 2 u svakom događaju; price_details ne sadrži third_party_cost_plus ni third_party_partial_delivery_deduction; opisi u tracking.event ne navode nijednu lokaciju koju je prijavio prevoznik; order.cancel_failed šalje kodove odbijanja prevoznika kao ORDER_CANCEL_REFUSED.
Vaš endpoint treba brzo da odgovori 2xx. Inače, u slučaju timeout-a ili nedostupnosti, isporuka se ponavlja.
Nalepite primljeni payload, vrednost Signature zaglavlja i vašu tajnu — alat ponovo izračunava potpis u pretraživaču (ništa ne napušta ovu stranicu) i javlja da li se poklapaju.
Okinite pravi, ispravno potpisan webhook sa našeg servera ka URL-u koji vi obezbedite. Korisno za testiranje dostupnosti prijemnika, parsiranja payload-a i logike verifikacije potpisa.
Pregledajte najnovije pokušaje isporuke webhook-a na vašem nalogu — i stvarne produkcione događaje i testove sa ove stranice. Nalepite Bearer token za učitavanje.
Zapisi o isporuci se čuvaju 90 dana.
Ručna ponovna isporuka dobija novi X-Webhook-Event-Id. event_id koji nosi sam događaj (pod.files_updated, order.deleted, događaji životnog ciklusa i narudžbina uređaja) zadržava prvobitnu vrednost.
| Vreme | Događaj | URL | Статус | HTTP | Pokušaj | Vreme (ms) | Тест? | Akcije |
|---|---|---|---|---|---|---|---|---|
| Još nema isporuka webhook-a. | ||||||||