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.

Zaregistrujte hook přes API:

POST /api/v1/hook

Nejdůležitější konfigurační parametry:

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

MLS (Message Level Status) je nástupcem staršího MLR a poskytuje odesílajicí straně zpětnou vazbu o přijetí a zpracování dokumentu. MLS není standardně aktivován a musí být nastaven pro každou party prostřednictvím capability reviews v konfiguraci SMP. Jakmile je MLS aktivován, PSB ho zpracovává automaticky: jako přijímající Service Provider odesílá PSB zprávu MLS zpět odesílateli po přijetí a doručení.

Když sami odesíláte dokumenty přes PSB, dostáváte zpětnou vazbu MLS od přijímající strany jako webhook událost na topicu MessageLevelStatusReceived. Jako přijímající Service Provider následuje samostatný webhook s topicem MessageLevelStatusSent, jakmile PSB vaším jménem odesle MLS odesílajícímu SP. Pomocí tohoto topicu sledujte, zda jsou vaše vlastní vydané MLS odpovědi správně doručovány.

PSB 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:

1. Získejte surový JSON payload z requestu.
2. Vypočítejte HMAC SHA256 hash pomocí Vašeho tajného klíče (stejný, který jste zadali při vytváření hooku).
3. Porovnejte vypočítaný hash s hodnotou v hlavičce X-EConnect-Signature.
4. Pokud se shodují, request je autentický.

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:

• IP whitelisting: omezte přicházející requesty na produkční IP adresy PSB (104.40.188.59 a 104.47.148.207)
• OAuth webhook autentizace: PSB se může autentizovat na Vašem endpointu pomocí OAuth2 credentials
• Mutual SSL: použijte klientské certifikáty pro vzájemnou TLS autentizaci

Pokud máte nakonfigurováno více hooků, PSB určí, který hook se použije, na základě:

1. Hooky na úrovni PartyId mají přednost před hooky na úrovni prostředí
2. Specifické topiky mají přednost před wildcardy
3. Pokud více hooků s filtry odpovídá stejnému topiku: vyhrává nejdelší filtr (podle počtu znaků) -- například filtr s další klauzulí && 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í.
4. Při stejné prioritě: hook-id jako rozhodující faktor

Kromě konkrétních topiků můžete také používat wildcard vzory k zachycení více typů událostí jedním hookem.

Níže jsou uvedeny běžné problémy s webhooky a jak je vyřešit.

PSB může přijmout příchozí fakturu, aniž by ji předal příjemci. Topic InvoiceReceived znamená, že PSB fakturu přijal; bez hooku na tomto topicu není nic odesláno na endpoint.

• Žádné chyby webhooku nejsou důkazem, že hook funguje. HookSentError existuje pouze tehdy, když je nakonfigurován hook, který se nedoručí.
• Hook mohl být mezitím odstraněn. Dřívější úspěšné doručení stejné straně/endpointu dokazuje, že hook existoval, ne že tam ještě je. Proto nejprve zkontrolujte aktuální konfiguraci hooku, než to budete považovat za první nastavení.
• Potvrzení příjmu na straně odesílatele není to samé jako doručení příjemcovu softwaru.

Chybějící hook opravte aktualizací stávajícího hooku místo jeho smazání a znovuvytvoření.

PSB 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:

• Nastavéní monitorování: přihlásit hook (např. mail-hook) k topicu 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í.
• Odstranienie příčiny: při chybě DNS zkontrolovat a obnovit DNS záznam domény endpointu; při timeoutech zajistit rychlejší odpověď endpointu (2xx do 100 sek., náročné zpracování asynchronně).
• Obnova změškaných událostí: události, které se během výpadku nezdařily, lze získat přes batch endpoint. Pětidenní okno opakování znamená, že včasná oprava v tomto období může ještě dohnat zásilání přes standardní doručování.

První linie: výpadek na straně zákazníka vs. technický problém (akceptace a produkce)

HookSentError, opakované HTTP 404 nebo "endpoint je offline"/"akceptační prostředí je vypnuto" může také vyplývat z toho, že zákazník dočasně vypne akceptační nebo produkční endpoint (vývoj, údržba). To není incident platformy eConnect.

1. Potvrdit příznak: HookSentError, endpoint offline nebo HTTP 404 na webhook endpointu nakonfigurovaném zákazníkem. Často viditelné jako přesný text Response status code does not indicate success: 404 (Not Found) (obvykle .NET HttpRequestException při odchozím požadavku hooku). Jde o 404 z vlastního endpointu zákazníka (vypnutý nebo špatná cesta), ne o chybu Peppol PartyId not found při odeslání (SMP 404), ani o REST resource 404 z obsluhy chyb API.
2. Zeptat se, zda je výpadek záměrný a dočasný (vývojáři/zákazník).
3. Potvrzeno jako dočasné → poznámka, žádná další akce na straně eConnectu, dokud endpoint opět není dostupný. Jakmile endpoint znovu vrací 2xx, lze změškané události získat přes batch endpoint.
4. Není záměrné nebo neznámé → postupovat podle standardního runbooku HookSentError výše (DNS/SSL/timeout, logy, monitorování, batch obnova).

• Používejte vždy HTTPS pro Váš webhook endpoint
• Implementujte idempotentní zpracování: PSB může ve vzácných případech doručit událost vícekrát
• Vraťte rychle 2xx stavový kód: PSB považuje každou ne-2xx odpověď za chybu a pokusí se o opětovné doručení
• Zaznamenávejte všechny přijaté události pro účely ladění a auditingu
• Používejte systém fronty (queue) na Vaší straně, pokud zpracování trvá déle, potvrďte přijetí nejprve a zpracujte poté

Chcete dokumenty raději získávat hromadně? Podívejte se na batch hook.