Webhook pošle na vašu adresu HTTP požiadavku vždy, keď v obchode nastane vybraná udalosť — napríklad zaplatenie objednávky. Slúži na prepojenie s vlastným systémom bez toho, aby ste museli dáta pravidelne sťahovať sami.
Kde to nájdete
Systém > Webhooky na /admin/webhooks.
1. Vytvorte webhook
- Otvorte
/admin/webhooksa kliknite na vytvorenie nového webhooku. - Vyplňte Názov (interné označenie) a URL — adresu musí prijímať
https://. - Voliteľne zadajte Secret — reťazec na podpis požiadavky (HMAC).
- Zaškrtnite jednu alebo viac udalostí, na ktoré má webhook reagovať. Tlačidlo „Vybrať všetky“ prepne celý zoznam naraz.
- Podľa potreby upravte Max. počet opakovaní (0–10) a Timeout (5–120 s).
- Uložte.
Polia a nastavenia
| Pole | Povinné | Význam |
|---|---|---|
| Názov | áno | Interné označenie webhooku v zozname |
| URL | áno | Cieľová adresa, musí byť platná URL |
| Secret | nie | Reťazec použitý na podpis X-Webhook-Signature; bez neho sa hlavička podpisu neposiela |
| Udalosti | áno, aspoň 1 | Zoznam udalostí, na ktoré webhook reaguje |
| Aktívny | nie | Vypnutý webhook sa nevolá vôbec |
| Max. počet opakovaní | nie (0–10) | Koľkokrát sa doručenie zopakuje po zlyhaní; 0 znamená bez opakovania |
| Timeout | nie (5–120 s) | Ako dlho sa čaká na odpoveď vášho servera |
Dostupné udalosti
Objednávky: order.placed, order.processing, order.paid, order.shipped, order.completed, order.cancelled, order.returned, order.refunded.
Vrátenia: return.requested, return.approved, return.rejected, return.received, return.refunded.
2. Overte podpis na svojej strane
Každá požiadavka nesie hlavičky X-Webhook-Event (názov udalosti) a X-Webhook-Delivery (ID konkrétneho pokusu). Ak má webhook vyplnený Secret, pridáva sa aj X-Webhook-Signature — HMAC-SHA256 z tela požiadavky, počítaný týmto secretom. Na svojej strane si telo požiadavky rovnako podpíšte a porovnajte s hlavičkou; požiadavku bez zhody odmietnite.
Pozor: Bez nastaveného secretu sa podpis neposiela vôbec — kdokoľvek, kto uhádne alebo odchytí URL, môže poslať falošnú požiadavku. Pre citlivé udalosti (platby, objednávky) secret vždy nastavte.
3. Sledujte doručenia
Na detaile webhooku otvorte Doručenia (/admin/webhooks/{id}/deliveries). Zoznam sa dá filtrovať podľa stavu a udalosti a hore vidíte súhrn (celkovo, úspešné, zlyhané, čakajúce). Pri zlyhanom doručení je k dispozícii tlačidlo na opätovné odoslanie s rovnakým telom.
Čo sa deje na pozadí
Webhook sa odosiela asynchrónne cez frontu; zlyhané doručenie sa opakuje s narastajúcim odstupom až do nastaveného počtu opakovaní, potom ostáva označené ako zlyhané. Vypnutie webhooku (Aktívny = nie) požiadavky úplne zastaví, história doručení zostáva zachovaná.
Asistentovi stačí napísať: „Vytvor webhook na order.paid pre https://…“, „Zobraz posledné doručenia webhooku X“ alebo „Zmaž webhook Y“ — AI vie webhook založiť, upraviť aj zmazať a pozrieť sa na históriu doručení vrátane odpovede servera.
Časté problémy
- Webhook sa nedá uložiť s URL na `http://` → adresa musí byť
https://, inak by citlivé dáta (napr. detail objednávky) odchádzali nezašifrované. - Doručenia zlyhávajú s timeoutom → váš server odpovedá pomalšie, než je nastavený timeout; buď timeout zvýšte, alebo spracovanie na svojej strane presuňte do frontu a odpovedzte hneď.
- Podpis na mojej strane nesedí → podpisuje sa presné telo požiadavky (JSON tak, ako bolo odoslané); akákoľvek úprava tela pred porovnaním podpis rozbije.
- Udalosť nikdy neprišla → skontrolujte, či je webhook Aktívny a či má danú udalosť skutočne zaškrtnutú — inak sa preň nespustí.
- Chcem opakovane testovať tú istú udalosť → použite tlačidlo opätovného odoslania pri konkrétnom doručení namiesto vyvolávania reálnej objednávky.