Udalosti
Connector webhooky
Zistíte, ako fungujú natívne Connector webhooky, čo robiť pri výpadku príjemcu a ako obnoviť spracovanie.
Predpoklady
- Aktívny Connector prístup a verejne dostupný HTTPS endpoint na vašej strane.
Kontrakt a doručenie
- 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
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.
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
Udalosti spracúvate idempotentne a po výpadku viete dorovnať stav bez duplicít.
Keď to nefunguje
- Duplicitná udalosť: spracujte ju ako opakovanie, nie ako nový doklad.
- Webhook nedostupný: obnovte dostupnosť a dorovnajte stav čítaním; nevytvárajte nové doklady.