/ docs
ProduktZnalostiVývojári
Platforma Control
Nastavenie a zabezpečenie webhookov

Konfigurácia webhookov v PSB: topiky, zabezpečenie HMAC SHA256 a IP whitelisting.

Webhooky sú primárny spôsob prijímania notifikácií v reálnom čase z PSB. Pri každej relevantnej udalosti, prijatej faktúre, zmene stavu, potvrdení doručenia, PSB odošle HTTP POST request na Váš endpoint s podrobnosťami o udalosti.

Ako webhooky v PSB fungujú?

V PSB zaregistrujete webhook ("hook") s URL a topikom. PSB následne odosiela všetky udalosti daného topiku na Vašu URL. Každá udalosť obsahuje príslušné dáta ako JSON payload.

Vytvorenie webhooku

Žiadne používateľské rozhranie k dispozícii: v súčasnosti nie je možné konfigurovať hook prostredníctvom používateľského rozhrania platformy. Hooky sa nastavujú cez API alebo prostredníctvom podpory eConnect. Rozhranie samoobsluhy pre hooky je v pláne (plánované na Q4 2026) a bude súčasťou Control (Platform 2.0): používatelia budú môcť hooky sami vytvárať, upravovať a mazať. Dovtedy nie je plánovaný žiadny podrobný návod na manuálnu konfiguráciu hookov cez API.

Zaregistrujte hook cez API:

POST /api/v1/hook

Najdôležitejšie konfiguračné parametre:

PolePopisurlHTTPS endpoint, na ktorý PSB odosiela udalostitopicTyp udalosti, na ktorú chcete reagovať (napr. InvoiceReceived)secretTajný kľúč na overenie HMAC podpisu

Poznámka: vyhnite sa rýchlemu mazaniu a opätovnému vytváraniu hookov pre rovnaké partyId a topik. Kvôli race conditions pri spracovaní úloh to môže dočasne viesť k tomu, že neexistuje žiadny aktívny hook, a udalosti tak nebudú doručené. Po zmazaní hooku chvíľu počkajte, kým vytvoríte nový, alebo namiesto zmazania a opätovného vytvorenia použite aktualizáciu.

Pridanie topiku k existujúcemu hooku

Chcete pridať ďalší topik (napr. InvoiceReceived) k existujúcemu hooku? Aktualizujte existujúcu konfiguráciu webhooku prostredníctvom štandardného API /hook, aby požadovaný topik bol zahrnutý v poli topics:

{
  "topics": ["InvoiceReceived"]
}

Aktualizujte existujúci hook namiesto jeho zmazania a opätovného vytvorenia. Zmazanie a opätovné vytvorenie spôsobuje race condition, pri ktorej môžu byť udalosti dočasne nedoručené (pozri upozornenie vyššie).

Nie je samoobslužné pre netechnických zákazníkov. Pridanie topiku k existujúcemu hooku je technická úloha: osoba, ktorá ju vykonáva, musí vedieť, kam má webhook smerovať (URL endpointu), a rozumieť tomu, čo je webhook. Netechnický zákazník to spravidla nemôže urobiť samostatne. Zapojte niekoho s technickými znalosťami (IT zákazníka alebo podpora eConnect).

Najpoužívanejšie topiky
TopikKedyInvoiceReceivedBola prijatá nákupná faktúraInvoiceSentPredajná faktúra bola úspešne odoslanáInvoiceSentErrorPredajná faktúra nemohla byť doručenáInvoiceSentRetryBol spustený pokus o opätovné odoslanieInvoiceResponseReceivedBola prijatá Invoice Response (stavové správy)OrderReceivedBola prijatá nákupná objednávka
Zabezpečenie webhookov pomocou HMAC

PSB zabezpečuje všetky doručenia webhookov pomocou HMAC SHA256 podpisov. Pri každom requeste PSB odosiela hlavičku:

X-EConnect-Signature: sha256={podpis}
Implementácia overenia

Na overenie podpisu:

  1. Získajte surový JSON payload z requestu.
  2. Vypočítajte HMAC SHA256 hash pomocou Vášho tajného kľúča (rovnaký, ktorý ste zadali pri vytváraní hooku).
  3. Porovnajte vypočítaný hash s hodnotou v hlavičke X-EConnect-Signature.
  4. Ak sa zhodujú, request je autentický.
Prevencia replay útokov

Skontrolujte tiež pole sentOn v payloade. Ak je tento časový údaj starší ako 5 minút, request odmietnite. Tým sa zabráni replay útokom, pri ktorých sa zachytený request neskôr opätovne prehrá.

Ďalšie bezpečnostné možnosti

Okrem HMAC overenia ponúka PSB ďalšie bezpečnostné vrstvy:

  • IP whitelisting: obmedzte prichádzajúce requesty na produkčné IP adresy PSB (104.40.188.59 a 104.47.148.207)
  • OAuth webhook autentifikácia: PSB sa môže autentifikovať na Vašom endpointe pomocou OAuth2 credentials
  • Mutual SSL: použite klientske certifikáty na vzájomnú TLS autentifikáciu
Poradie priorít

Ak máte nakonfigurovaných viacero hookov, PSB určí, ktorý hook sa použije, na základe:

  1. Hooky na úrovni PartyId majú prednosť pred hookmi na úrovni prostredia
  2. Špecifické topiky majú prednosť pred wildcardmi
  3. Ak viacero hookov s filtrami zodpovedá rovnakému topiku: vyhráva najdlhší filter (podľa počtu znakov) -- napríklad filter s ďalšou klauzulou && vyhráva nad kratším filtrom bez tejto klauzuly. Zabraňuje to duplicitnému doručeniu bez toho, aby sa filtre musely vzájomne vylučovať.
  4. Pri rovnakej priorite: hook-id ako rozhodujúci faktor
Riešenie problémov

Nižšie sú uvedené bežné problémy s webhookmi a ich riešenia.

PríznakPríčinaRiešenieWebhooki nedochádzajúEndpoint nedostupný (timeout 100 sek.)Vyžadované HTTPS + platný SSL certifikát; deaktivovať ochranu CSRF na webhook endpointeWebhook odmietaný ako nezabezpečenýValidácia X-EConnect-Signature zlyháSkontrolovať výpočet HMAC SHA256: payload × secret → šestnástkový reťazec s prefixom sha256=Replay útoK zablokovanýPole sentOn staršie ako 5 minútEndpoint spracováva príliš pomaly alebo sú hodiny nastavené neprávne"No such host is known" (chyba DNS)Názov hostiteľa webhook endpointu už nie je rozložiteľný, napr. po premenovaní prostredia ERP alebo vypršaní DNS záznamuSkontrolovať a obnoviť DNS záznam domény endpointu; potom získat zmeškané udalosti cez batch endpointHookSentError (definitlvne zlyhanie)PSB sa pokršal 5 dní bez odpovede 2xxSkontrolovať logy endpointu; monitorovať topic HookSentError (pozri nižšie); získat zmeškané udalosti cez batch endpointStaré faktúry opätovĞ doručenéAPI pri prvom prijímaní nevracá 2xxEndpoint musí vždy vracať 2xx, aj pri asynchrónnom spracovaníDuplicitné spracovanie pri opakovaníŽiadna kontrola idempotentnostiPoužiť hlavičku X-EConnect-Delivery (unikátne UUID) na deduplikáciu
Monitorovanie a obnova po HookSentError

PSB posiela webhook udalosti (napr. InvoiceReceived pri prijíaní e-faktúry) na konfigurovaný endpoint. Ak tento endpoint nie je dostupný — kvôli timeoutu, chybe SSL alebo chybe DNS ako No such host is known — PSB opakuje s exponenciálnym spätným krokom po dobu 5 dní (timeout 100 sek. na pokus). Každý pokus generuje udalosť HookSentRetry; po 5 dňoch bez odpovede 2xx je vydaný HookSentError ako konečný stav a PSB prestáva opakovať.

Dôsledok: prijatá e-faktúra nebude doručená zákazníkovi, kým je endpoint nedostupný, bez toho aby si to zákazník priamo všimol. Odporúčané kroky:

  • Nastaviť monitorovanie: prihlať hook (napr. mail-hook) k topiku HookSentError, aby definitlvne zlyhanie doručovania bolo aktlvne signalizované namiesto tichého prechodzenia. Zvážiť aj HookSentRetry pre skoré odhalenie.
  • Odstrániť príčinu: pri chybe DNS skontrolovať a obnoviť DNS záznam domény endpointu; pri timeoutoch zabezpečiť rýchlejšiu odpoveď endpointu (2xx do 100 sek., náročné spracovanie asynchrónne).
  • Obnova zmeškaných udalostí: udalosti, ktoré počas výpadku zlyhali, možno získat cez batch endpoint. Päť-dňové okno opakovaní znamená, že včasná oprava v tomto období môže ešte dobehnúť doručovanie cez štandardné doručovanie.
Osvedčené postupy
  • Používajte vždy HTTPS pre Váš webhook endpoint
  • Implementujte idempotentné spracovanie: PSB môže v zriedkavých prípadoch doručiť udalosť viackrát
  • Vráťte rýchlo 2xx stavový kód: PSB považuje každú nie-2xx odpoveď za chybu a pokúsi sa o opätovné doručenie
  • Zaznamenávajte všetky prijaté udalosti na účely ladenia a auditingu
  • Používajte systém frontu (queue) na Vašej strane, ak spracovanie trvá dlhšie, potvrďte prijatie najprv a spracujte potom
Často kladené otázky
Ako overím prichádzajúci webhook pomocou HMAC SHA256?

Vezmite surové JSON telo requestu, vypočítajte HMAC SHA256 hash pomocou secretu, ktorý ste zadali pri vytváraní hooku, a porovnajte ho s hodnotou v hlavičke X-EConnect-Signature (za prefixom sha256=). Ak sa zhodujú, viete, že request pochádza z PSB a nebol počas prenosu upravený.

Prečo je potrebné kontrolovať pole sentOn v payloade?

Overte, či sentOn nie je starší ako 5 minút. Ak je časová značka príliš stará, request odmietnite. Tým zabránite útokom typu replay, pri ktorých sa skôr zachytený request znova odošle neskôr, aj keď je podpis technicky správny.

Ako predísť problémom s idempotentným spracovaním a opakovaním?

Implementujte idempotentné spracovanie na Vašej strane, pretože PSB môže v zriedkavých prípadoch doručiť udalosť viackrát. Taktiež rýchlo vráťte HTTP 2xx stavový kód: každá iná odpoveď sa považuje za chybu a spustí opakovanie. Pre náročné spracovanie najprv potvrďte príjem a potom spracujte cez front.

Chcete dokumenty radšej získavať hromadne? Pozrite sa na batch hook.

Pozrite si webhook endpointy

PreviousTok dokumentu a stav
NextE-mail hooky