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.

Vodič za Webhook Integraciju
Centar za Programere Početna

Vodič za Webhook Integraciju

Šta su webhook-ovi?

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.

Kako isporuka funkcioniše

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.

Sigurnosni model

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.

Katalog Događaja

Dostupno je osam tipova odlaznih događaja. Svaki ima svoj URL na stranici podešavanja — pretplatite se na bilo koji podskup.

ред.створен

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-a
ордер.статус_цханге

Okida se pri svakoj promeni statusa — preuzeto, u tranzitu, isporučeno, izuzetak, otkazano. Konfigurišite pomoću order_status_change_webhook_url.

Primeri Payload-a
праћење.догађај

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.

Primeri Payload-a
ордер.цреате_асинц

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.

Primeri Payload-a
POD fajlovi ažurirani

Okida 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.

Primeri Payload-a
Porudžbina obrisana

Okida 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-a
Otkazivanje porudžbine nije uspelo

Okida 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-a
Promena mesta na tabli ruta

Aktivira 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-a

Događaji dobavljačskih ormarića

Odvojen 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.

partner_locker.delivery.doors_opened

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-a
partner_locker.delivery.delivered

Isporuč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-a
partner_locker.pickup.completed

Preuzeto — Okida se kada primalac preuzme odložene pakete.

Primeri Payload-a
partner_locker.delivery.failed

Isporuka neuspešna — Okida se kada isporuka ne uspe; uključeni su kodovi grešaka po paketu.

Primeri Payload-a
partner_locker.delivery.expired

Isteklo — Okida se kada neiskorišćeni kôd za isporuku ili nepreuzeto odlaganje pređe rok važenja.

Primeri Payload-a
partner_locker.delivery.cancelled

Otkazano — Okida se kada se isporuka otkaže pre završetka.

Primeri Payload-a
partner_locker.delivery.correction_reopened

Ponovno 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-a
partner_locker.delivery.code_rotated

partner_locker_delivery.event_type_code_rotated — 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-a

Potpis 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.

Događaji isporuke trećih strana

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.

delivery.assignment.created

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-a
delivery.assignment.handed_over

Paketi predati — Aktivira se kada je magacin fizički predao sve pakete dodele dobavljaču.

Primeri Payload-a
delivery.assignment.cancelled

Dodela 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-a
delivery.assignment.partial_delivered

Delimič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-a

Potpis 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.

Događaji životnog ciklusa porudžbine

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.

order.assigned

Porudžbini je dodeljen vozač (ručno, planiranjem ruta ili automatskom dodelom). data.source = auto_assign kada je to uradio orkestrator.

Primeri Payload-a
order.unassigned

Porudžbina je izgubila vozača (predaja, opoziv, odbijanje, istek vremena). data.previous_driver_id pokazuje ko ju je imao.

Primeri Payload-a
order.accepted

Vozač je u aplikaciji prihvatio automatski dodeljenu porudžbinu (smena vozača sa obaveznim prihvatanjem).

Primeri Payload-a
order.rejected

Vozač je odbio dodeljenu porudžbinu; data.reason nosi opcioni razlog u slobodnom tekstu.

Primeri Payload-a
order.pickup_started

Vozač je započeo preuzimanje (status Preuzimanje započeto / Na preuzimanju).

Primeri Payload-a
order.picked_up

Paket je preuzet (status Već preuzeto).

Primeri Payload-a
order.on_the_way

Paket je na putu ka primaocu (status Dostava započeta / U dostavi).

Primeri Payload-a
order.completed

Dostava je uspela (status Uspešno).

Primeri Payload-a
order.failed

Pokušaj dostave nije uspeo (Ponovo dostaviti kasnije, Potrebno ponovno planiranje, Odbio primalac).

Primeri Payload-a
order.cancelled

Porudžbina je otkazana.

Primeri Payload-a
order.ready

Osoblje (ili vozač, kada je dozvoljeno) je označilo porudžbinu kao spremnu za preuzimanje (Opcije dispečinga → spremno za preuzimanje).

Primeri Payload-a
driver.on_duty_changed

Vozač je u aplikaciji započeo ili završio smenu (opcija smene vozača).

Primeri Payload-a
driver.location_update

Pozicija 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-a

Kako 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.

Događaji porudžbina na uređajima

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.

device_order.stored

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-a
device_order.collected

Paket je preuzela osoba koju je čekao — primalac, kurir ili osoblje koje prazni pametni sandučić.

Primeri Payload-a
device_order.removed

Osoblje je izvadilo paket iz uređaja. removal_reason navodi razlog: overdue_return, handover, relay, anomaly ili recovery.

Primeri Payload-a
device_order.overdue

Paket 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-a
device_order.exception_opened

Otvoren 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-a
device_order.exception_resolved

Neko je zatvorio problem u vezi sa rukovanjem. data.exception.status je resolved ili dismissed, a resolution_action navodi šta je urađeno.

Primeri Payload-a

Primeri 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.

Kako Konfigurisati

Webhook-ove možete konfigurisati na dva nivoa: na nivou kompanije (pokriva sve) ili po klijentu (preglašava za taj specifični B2B podnaloga).

1. Idite na podešavanja

Prijavite se i idite na Podešavanja → API i Webhook-ovi. Preglašavanja po klijentu su na stranici detalja klijenta.

2. Postavite tajnu za potpisivanje

Odaberite string od najmanje 16 karaktera, idealno 32+ slučajnih bajtova. Vaš prijemnik koristi ovu tajnu za verifikaciju potpisa.

3. Postavite željene URL-ove događaja

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.
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.
Vodič kroz novine u integraciji

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.

Potpis i Verifikacija

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.

Algoritam
HMAC-SHA256 (hex)
Ime zaglavlja
Signature
Koraci verifikacije
  1. Pročitajte sirovo telo pre nego što ga parsing ili middleware izmene.
  2. Izračunajte hash_hmac('sha256', rawBody, sharedSecret) i kodirajte u hex.
  3. Uporedite sa Signature zaglavljem u konstantnom vremenu (hash_equals u PHP, crypto.timingSafeEqual u Node).
  4. Odgovorite 2xx samo ako se potpisi poklope. Inače 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

Ponavljanja i Pouzdanost

Vaš endpoint treba brzo da odgovori 2xx. Inače, u slučaju timeout-a ili nedostupnosti, isporuka se ponavlja.

Maksimalno pokušaja
5 (početni + 4 ponavljanja)
Timeout po pokušaju
3 sekunde
Бацкофф
Eksponencijalno — približno 10s, 100s, 1000s, 10000s
Projektujte za idempotentnost. Pošto se isporuka može ponoviti, prijemnik može videti isti događaj više puta. Koristite ID porudžbine/praćenja kao ključ za deduplikaciju — čuvajte obrađene ID-jeve najmanje 24 sata.
Preporučeni odgovor. Brzo potvrdite (HTTP 200) i obradite asinhrono. Izbegavajte spore operacije sinhrono u handler-u — pogodićete 3-sekundni timeout.

Verifikator Potpisa

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.

Pošalji Test Webhook

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.

Nedavne Isporuke Webhook-a

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.

Vreme Događaj URL Статус HTTP Pokušaj Vreme (ms) Тест? Akcije
Još nema isporuka webhook-a.

Najbolje Prakse

© 2026 superRoute. Centar za Programere