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.

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.

Zaregistrujte hook cez API:

POST /api/v1/hook

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

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

MLS (Message Level Status) je nástupcom staršieho MLR a poskytuje odosielajúcej strane spätnú väzbu o prijatí a spracovaní dokumentu. MLS nie je štandardne aktivovaný a musí byť nastavený pre každú party prostredníctvom capability reviews v konfigurácii SMP. Hneď ako je MLS aktivovaný, PSB ho spracováva automaticky: ako prijímajúci Service Provider odosiela PSB správu MLS späť odosielateľovi po prijatí a doručení.

Keď sami odosielate dokumenty cez PSB, dostávate spätnú väzbu MLS od prijímajúcej strany ako webhook udalosť na topicu MessageLevelStatusReceived. Ako prijímajúci Service Provider nasleduje samostatný webhook s topicom MessageLevelStatusSent, hneď ako PSB vo vašom mene odošle MLS odosielajúcemu SP. Pomocou tohto topiku sledujte, či sú vaše vlastné vydané MLS odpovede správne doručované.

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}

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

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

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

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

Okrem konkrétnych topikov môžete tiež používať wildcard vzory na zachytenie viacerých typov udalostí jedným hookom.

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

PSB môže prijať dochádzajúcu faktúru bez toho, aby ju odovzdal prijímajúcej strane. Topic InvoiceReceived znamená, že PSB faktúru prijal; bez hooku na tomto topicu sa nič neodosiela na endpoint.

• Žiadne chyby webhooku nie sú dôkazom, že hook funguje. HookSentError existuje iba vtedy, keď je nakonfigurovaný hook, ktorý zlyháva pri doručení.
• Hook mohol byť medzitým odstránený. Predchádzajúce úspešné doručenie rovnakej strane/endpointu dokazuje, že hook existoval, nie že je tam stále. Preto najprv skontrolujte aktuálnu konfiguráciu hooku, namiesto toho, aby ste to považovali za prvé nastavenie.
• Potvrdenie prijatia na strane odosielateľa nie je to isté ako doručenie prijímajúcemu softvéru.

Chýbajúci hook opravte aktualizáciou existujúceho hooku namiesto jeho vymazania a opätovného vytvorenia.

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.

Prvá línia: výpadok na strane zákazníka vs. technický problém (akceptácia a produkcia)

HookSentError, opakované HTTP 404 alebo "endpoint je offline"/"akceptačné prostredie je vypnuté" môže tiež vyplývať z toho, že zákazník dočasne vypne akceptačný alebo produkčný endpoint (vývoj, údržba). To nie je incident platformy eConnect.

1. Potvrdiť symptóm: HookSentError, endpoint offline alebo HTTP 404 na webhook endpointe nakonfigurovanom zákazníkom. Často viditeľné ako presný text Response status code does not indicate success: 404 (Not Found) (zvyčajne .NET HttpRequestException pri odchodzom požiadavku hooku). Ide o 404 z vlastného endpointu zákazníka (vypnutý alebo nesprávna cesta), nie o chybu Peppol PartyId not found pri odosielaní (SMP 404), ani o REST resource 404 zo spracovania chýb API.
2. Opýtať sa, či je výpadok zámerný a dočasný (vývojári/zákazník).
3. Potvrdené ako dočasné → poznamenať, žiadna ďalšia akcia na strane eConnectu, kým endpoint opäť nie je dostupný. Hneď ako endpoint znova vracia 2xx, možno zmeškané udalosti získať cez batch endpoint.
4. Nie je zámerné alebo neznáme → postupovať podľa štandardného runbooku HookSentError vyššie (DNS/SSL/timeout, logy, monitorovanie, batch obnova).

• 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

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