Konfigurace webhooků v PSB: topiky, zabezpečení HMAC SHA256 a IP whitelisting.
Webhooky jsou primární způsob přijímání notifikací v reálném čase z PSB. Při každé relevantní události, přijaté faktuře, změně stavu, potvrzení doručení, PSB odešle HTTP POST request na Váš endpoint s podrobnostmi o události.
V PSB zaregistrujete webhook ("hook") s URL a topikem. PSB následně odesílá všechny události daného topiku na Vaši URL. Každá událost obsahuje příslušná data jako JSON payload.
Žádné uživatelské rozhraní k dispozici: v současné době není možné konfigurovat hook přes uživatelské rozhraní platformy. Hooky se nastavují přes API nebo přes podporu eConnect. Rozhraní samoobsluhy pro hooky je v plánu (plánované na Q4 2026) a bude součástí Control (Platform 2.0): uživatelé pak budou moci hooky sami vytvářet, upravovat a mazat. Do té doby není plánován žádný podrobný návod pro ruční konfiguraci hooků přes API.
Zaregistrujte hook přes API:
POST /api/v1/hook
Nejdůležitější konfigurační parametry:
InvoiceReceived)Poznámka: vyhněte se rychlému mazání a opětovnému vytváření hooků pro stejné partyId a topik. Kvůli race conditions při zpracování úloh to může dočasně vést k tomu, že neexistuje žádný aktivní hook, a události tak nebudou doručeny. Po smazání hooku chvíli počkejte, než vytvoříte nový, nebo místo smazání a opětovného vytvoření použijte aktualizaci.
Chcete přidat další topik (např. InvoiceReceived) k existujícímu hooku? Aktualizujte stávající konfiguraci webhooku prostřednictvím standardního API /hook, aby požadovaný topik byl obsažen v poli topics:
{
"topics": ["InvoiceReceived"]
}
Aktualizujte stávající hook místo jeho smazání a opětovného vytvoření. Mazání a opětovné vytváření způsobuje race condition, při které mohou být události dočasně nedoručeny (viz upozornění výše).
Není samoobslužnou pro netechnické zákazníky. Přidání topiku k existujícímu hooku je technický úkol: osoba, která jej provádí, musí vědět, kam má webhook směřovat (URL endpointu), a rozumět tomu, co je webhook. Netechnický zákazník to zpravidla nemůže udělat samostatně. Zapojte někoho s technickými znalostmi (IT zákazníka nebo podpora eConnect).
InvoiceReceivedInvoiceSentInvoiceSentErrorInvoiceSentRetryInvoiceResponseReceivedOrderReceivedPSB zabezpečuje všechna doručení webhooků pomocí HMAC SHA256 podpisů. Při každém requestu PSB odesílá hlavičku:
X-EConnect-Signature: sha256={podpis}
Pro ověření podpisu:
X-EConnect-Signature.Zkontrolujte také pole sentOn v payloadu. Pokud je tento časový údaj starší než 5 minut, request odmítněte. Tím se zabrání replay útokům, při kterých se zachycený request později opětovně přehraje.
Kromě HMAC ověření nabízí PSB další bezpečnostní vrstvy:
104.40.188.59 a 104.47.148.207)Pokud máte nakonfigurováno více hooků, PSB určí, který hook se použije, na základě:
&& vyhrává nad kratším filtrem bez této klauzule. To zabraňuje duplicitnímu doručení, aniž by filtry musely být vzájemně vylučující.Níže jsou uvedeny běžné problémy s webhooky a jak je vyřešit.
sha256=sentOn starší než 5 minutHookSentError (viz níže); získat změškané události přes batch endpointX-EConnect-Delivery (unikátní UUID) pro deduplikaciPSB posílá webhook události (např. InvoiceReceived při přijetí e-faktury) na konfigurovaný endpoint. Pokud tento endpoint není dostupný — kvůli timeoutu, chybě SSL nebo chybě DNS jako No such host is known — PSB opakuje s exponenciálním zpětným krokem po dobu 5 dní (timeout 100 sek. na pokus). Každý pokus generuje událost HookSentRetry; po 5 dnech bez odpovědi 2xx je vydán HookSentError jako konečný stav a PSB přestává opakovat.
Důsledek: přijatá e-faktura nebude doručena zákazníkovi, dokud je endpoint nedostupný, aniž by to zákazník přímo zjistil. Doporučené kroky:
HookSentError, aby bylo definitivní selhání doručení aktivně signalizováno místo tichého přeskokování. Zvážit také HookSentRetry pro včasné odhalení.Vezměte surové JSON tělo requestu, vypočítejte HMAC SHA256 hash pomocí secretu, který jste zadali při vytváření hooku, a porovnejte ho s hodnotou v hlavičce X-EConnect-Signature (za prefixem sha256=). Pokud se shodují, víte, že request pochází z PSB a nebyl během přenosu upraven.
Ověřte, že sentOn není starší než 5 minut. Pokud je časové razítko příliš staré, request odmítněte. Tím zabráníte útokům typu replay, při kterých se dříve zachycený request znovu odešle později, i když je podpis technicky správný.
Implementujte idempotentní zpracování na Vaší straně, protože PSB může ve vzácných případech doručit událost vícekrát. Také rychle vraťte HTTP 2xx stavový kód: každá jiná odpověď se považuje za chybu a spustí opakování. Pro náročné zpracování nejprve potvrďte příjem a poté zpracujte přes frontu.
Chcete dokumenty raději získávat hromadně? Podívejte se na batch hook.
Podívejte se na webhook endpointy