Webhook

Webhook doručuje infrastruktura někoho jiného a ta jejich síť není o nic spolehlivější než vaše. Odesílatel opakuje doručení, když vám endpoint vyprší, takže stejné oznámení o platbě může přijít třikrát. Každý handler musí být idempotentní: událost najděte podle id a když už byla zpracovaná, přeskočte ji.

Odpovídejte rychle a zpracujte později. Když handler posílá PDF faktury přímo v HTTP požadavku a trvá čtyři sekundy, odesílatel může vypršet a doručení zopakovat, zatímco první pokus stále běží. Událost uložte a předejte do fronty.

Na veřejnou URL může poslat POST kdokoli. Zprávě o platbě věřte jen tehdy, když požadavek nese platný podpis přes surové tělo se sdíleným tajemstvím, a všechno nepodepsané odmítněte. Ověřujte surová data, ne naparsovaný JSON — serializace mění pořadí klíčů a hash přestane sedět.

Uložte surový payload a id události hned, jak projdou ověřením. Když se zákazník ozve, že objednávka nebyla zaplacená, log je rozdíl mezi „brána nám to nikdy neposlala“ a „přišlo to a my to zahodili“. Většina bran navíc umí doručení poslat znovu — právě replay často zachrání účet.

Webhook funguje jen tehdy, dokud je váš endpoint dostupný, a velká platební brána nebude čekat na staging server dodavatele. U všeho kritického ho spojte s pravidelnou rekoncilací, která jednou za hodinu porovná otevřené objednávky proti API brány. Když platba prošla a webhook se ztratil, tahle úloha to zachytí.

Stejná pravidla platí pro webhooky, které posíláte ven: opakování s rostoucí prodlevou, podpisové tajemství a zdokumentované chování pro nedoručené události. Webhook, který posíláte, je vaše API bez požadavku.