Webhooky pre vývojárov — payload, podpis a opakovania

Webhook doručí udalosť objednávky alebo vrátenia na vašu URL vo formáte JSON, s hlavičkou obsahujúcou HMAC podpis. Nastavenie webhooku v administrácii opisuje Webhooky — tento článok je referencia pre stranu, ktorá payload prijíma a spracúva.

Kde to nájdete#

Nastavenia > Webhooky na /admin/webhooks — zoznam, vytvorenie, história doručení (počet úspešných a zlyhaných pokusov).

1. Dostupné udalosti#

Jeden webhook môže počúvať na viacero udalostí naraz — vyberiete ich pri vytváraní na /admin/webhooks/create.

2. Tvar payloadu#

Objednávkové udalosti:

{
  "event": "order.paid",
  "timestamp": "2026-09-12T10:15:00+00:00",
  "data": {
    "id": 1234,
    "order_number": "OBJ-2026-001234",
    "status": "paid",
    "total": 89.9,
    "currency": "EUR",
    "customer_email": "zakaznik@example.com",
    "items_count": 3,
    "created_at": "2026-09-12T09:58:11+00:00",
    "updated_at": "2026-09-12T10:15:00+00:00"
  }
}

Udalosti vrátenia:

{
  "event": "return.approved",
  "timestamp": "2026-09-12T10:15:00+00:00",
  "data": {
    "id": 55,
    "return_number": "VR-2026-000055",
    "order_id": 1234,
    "status": "approved",
    "reason": "Nesprávna veľkosť",
    "refund_amount": 29.9,
    "created_at": "2026-09-11T08:00:00+00:00",
    "updated_at": "2026-09-12T10:15:00+00:00"
  }
}

data nesie vždy len bezpečné, nekritické polia objednávky/vrátenia — nie interné poznámky ani platobné údaje.

3. Hlavičky requestu#

4. Overenie podpisu#

Podpis je hash_hmac('sha256', json_encode(payload), secret). Vo vašom endpointe prepočítajte rovnaký HMAC nad presne prijatým telom (nie nad preparsovaným a znovu serializovaným JSON — poradie kľúčov by sa mohlo líšiť) a porovnajte ho v konštantnom čase:

$expected = hash_hmac('sha256', $rawRequestBody, $secret);
if (! hash_equals($expected, $request->header('X-Webhook-Signature'))) {
    abort(401);
}

import crypto from 'node:crypto';

function verify(rawBody: string, signature: string, secret: string) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Pozor: Webhook bez nastaveného secretu hlavičku X-Webhook-Signature vôbec neposiela. Pri citlivom endpointe secret vždy nastavte a request bez platnej hlavičky odmietnite.

5. Doručenie, opakovania a timeout#

• Každé doručenie beží asynchrónne na vyhradenej fronte (webhooks), takže objednávka sa neoneskorí kvôli pomalému alebo nedostupnému endpointu.
• Váš endpoint má na odpoveď nastavený timeout definovaný na webhooku; po jeho prekročení sa pokus počíta ako zlyhaný.
• Pri zlyhaní (chybový status alebo timeout) sa doručenie opakuje s odstupom 10 s, 60 s, 300 s, maximálne toľkokrát, koľko udáva maximálny počet pokusov webhooku. Hodnota 0 doručenie úplne vypne.
• História každého pokusu (status kód, telo odpovede, čas doručenia) je v administrácii pri danom webhooku — pri ladení integrácie je prvý krok práve tam, nie v logoch servera.
• Vracajte 2xx iba po úspešnom spracovaní. Návrat 2xx predtým, než skutočne uložíte dáta, a následné zlyhanie na vašej strane znamená, že sa udalosť už nikdy nezopakuje.

Časté problémy#

• Endpoint nedostáva nič. Skontrolujte, či je webhook aktívny a či počúva na danú udalosť; história doručení v administrácii ukáže, či sa o pokus vôbec pokúsila.
• Podpis nesedí. Najčastejšia príčina je prepočítanie HMAC nad telom, ktoré po ceste prešlo cez framework a zmenilo poradie kľúčov alebo medzery — počítajte podpis nad surovým telom requestu.
• Duplicitné spracovanie tej istej udalosti. Endpoint musí byť idempotentný — pri opakovanom pokuse dorazí rovnaký X-Webhook-Delivery, podľa ktorého viete duplicitu rozpoznať.
• Doručenia stále zlyhávajú. Skontrolujte, že endpoint odpovie do nastaveného timeoutu a vždy vráti 2xx pri úspechu — 3xx presmerovanie sa nenasleduje.
• Webhook prestal doručovať úplne. Maximálny počet pokusov mohol byť nastavený na 0, čím sa doručovanie efektívne vypína.

Súvisí#

• Webhooky
• Headless Storefront API
• MCP server — pripojenie Claude k obchodu