Webhooky

Rozcestník

Čo platí pre všetky udalosti

• Udalosť nie je náhrada vlastného uloženia; spracujte ju idempotentne a overte podpis alebo pôvod.
• Zlyhané doručenie má vlastný obnovovací postup; neposielajte tie isté údaje znovu naslepo.
• Tajomstvá webhooku patria na server, nikdy do browsera.

Enterprise webhooky

Nastavíte Enterprise odber udalostí alebo pull režim a viete, ako overiť doručenie a obnoviť spracovanie.

• webhooks:write na vytvorenie odberu aj potvrdenie udalostí a webhooks:read na ich čítanie; pri centrálnom partnerskom JWT aj X-Firm-Id oprávnenej firmy.

Odber alebo pull

• Vytvorenie odberu a Node.js príklad overenia podpisu
• Pull fronta: odpoveď a potvrdenie udalostí
• Obnova terminálneho doručenia

1. 1

   Vytvorte odber udalostí

   POST /api/v1/webhooks s HTTPS url a events vytvorí push odber; url: null vytvorí pull-only odber. Aj pull vyžaduje vytvorenie odberu. Zariaďte ho pred testovacou operáciou: historické udalosti sa spätne nedopĺňajú. Secret bezpečne uložte, zobrazuje sa iba raz.

2. 2

   Overte doručenie

   X-Webhook-Timestamp je Unix čas v sekundách. X-Webhook-Signature je sha256=<64 lowercase hex>; HMAC-SHA256 počítajte nad timestamp + '.' + rawBody pred parsovaním JSON. Overte odchýlku najviac 300 sekúnd a podpis porovnajte v konštantnom čase; funkčný príklad je v pripojenej referencii.

3. 3

   Dorovnajte stav po výpadku

   Pri pull odbere čítajte GET /api/v1/events/pull (limit najviac 100), ukladajte udalosti a až po commite potvrďte event_id cez POST /api/v1/events/{eventId}/ack. Pri has_more=true pokračujte. Ak odber v čase udalosti neexistoval, rekonštruujte stav z dokumentov; pri zlyhanom push doručení použite históriu doručení a dead-letter replay podľa referencie.

Hranice Enterprise udalostí

• Enterprise udalosti nie sú náhradou Connector webhooku; kontrakty, secrete aj testy zostávajú oddelené.
• Nezamieňajte udalosť o doručení s obchodnou odpoveďou druhej strany.

Očakávaný výsledok a chyby

Máte funkčný odber alebo pull a viete, kedy je doklad doručený a kedy iba prijatý na spracovanie.

• Stavy dokumentov
• Enterprise firmy
• Diagnostika chýb

• Udalosť nechodí: overte, či odber vznikol a či callback prešiel overením podpisu.
• Udalosť prišla pred uložením dokladu: po uložení dorovnajte stav čítaním.

Connector webhooky

Zistíte, ako fungujú natívne Connector webhooky, čo robiť pri výpadku príjemcu a ako obnoviť spracovanie.

• Aktívny Connector prístup a verejne dostupný HTTPS endpoint na vašej strane.

Kontrakt a doručenie

• Nastavenie webhooku: telo, oprávnenia a odpoveď
• Quickstart vrátane overenia podpisu

• PUT /api/v1/connector/webhook nastavuje webhook pre integrátora so scope webhooks:write. Podpis X-Webhook-Signature má tvar sha256=<hex>; HMAC-SHA256 počítajte nad X-Webhook-Timestamp + '.' + pôvodnými bajtmi tela. Timestamp je v sekundách; overte toleranciu 300 sekúnd a podpis porovnajte v konštantnom čase ešte pred parsovaním JSON.
• Deduplikujte podľa X-Webhook-Event-Id. Úspech potvrďte až po trvalom uložení udalosti do vlastnej fronty; pri dočasnej chybe použite 503. Connector považuje 500 za terminálnu odpoveď bez retry.
• Connector webhook doručuje udalosti dokladu pre váš Connector prístup a je oddelený od Enterprise odberov.
• Endpoint odpovedá rýchlo a spracovanie robí asynchrónne, aby výpadok nespôsobil stratu.
• Tajomstvo webhooku držte na serveri a pre každé prostredie použite vlastné.

Obnova po výpadku

1. 1

   Dorovnajte stav čítaním

   Volajte GET /api/v1/connector/events s customerRef a posledným cursor. nextCursor uložte až po lokálnom commite a použite ho aj keď hasMore=false. Pri strate alebo odmietnutí cursor začnite bez neho a deduplikujte podľa event id. Polling obnovuje dokumentové udalosti, nie všetky lifecycle notifikácie.

2. 2

   Potvrďte len skutočne uložené

   Potvrdenie pošlite až po uložení dokladu vo vašom systéme.

Očakávaný výsledok a chyby

Udalosti spracúvate idempotentne a po výpadku viete dorovnať stav bez duplicít.

• Enterprise webhooky
• Stavy dokumentov
• Idempotencia

• Duplicitná udalosť: spracujte ju ako opakovanie, nie ako nový doklad.
• Webhook nedostupný: obnovte dostupnosť a dorovnajte stav čítaním; nevytvárajte nové doklady.