Shoptet posiela dáta priamo vo webhooku. Čo to mení pre integrácie

Shoptet 29. septembra zapol pri webhookoch voliteľné odosielanie payloadu. Notifikácia tak môže po novom niesť rovno kompletné dáta entity — objednávky, produktu, zákazníka, faktúry a ďalších. Pre integrácie to znamená, že na jednu zmenu stačí jedno doručenie namiesto dvojice „notifikácia + dopyt do API".

Znie to ako detail. V prevádzke integrácií, ktoré synchronizujú e-shop s ERP, skladom alebo CRM, je to však jedna z tých zmien, ktoré sa prejavia na stabilite.

Ako to fungovalo doteraz

Model bol jednoduchý a všetci ho poznajú: Shoptet pošle na váš endpoint notifikáciu v štýle „objednávka 2026000123 bola vytvorená". Notifikácia sama o sebe žiadne dáta neobsahuje. Aplikácia si ich musela dotiahnuť — zavolať detailný endpoint objednávky a až potom mohla niečo spracovať.

Každá zmena na e-shope teda stála minimálne dve sieťové operácie a jedno volanie API navyše. Pri e-shope, kde sa v sezóne menia ceny a stavy objednávok v ráde tisícov udalostí denne, sa to sčítava.

Čo sa zmenilo

Notifikácia môže po novom obsahovať pole payload s dátami entity:

{
  "eshopId": 1,
  "event": "order:create",
  "eventCreated": "2026-09-29T10:00:00+0200",
  "eventInstance": "2026000123",
  "payload": {
    "data": {
      "order": { ... }
    }
  }
}

Obsah payload zodpovedá tomu, čo by vrátil detailný endpoint danej entity — vrátane všetkých parametrov include, ktoré sú preň dostupné. Nie je to teda skrátený výťah, ale tie isté dáta, pre ktoré sa doteraz volalo zvlášť.

Ako sa to zapína

Explicitne, pri registrácii alebo úprave webhooku, parametrom sendPayload:

{
  "data": [
    {
      "event": "order:create",
      "url": "https://myapplication.tld/orders.php",
      "sendPayload": "full"
    }
  ]
}

Nič sa nedeje samo. Bez tohto parametra sa správanie nemení, takže žiadnu existujúcu integráciu to nerozbije. Je to opt-in na úrovni jednotlivého webhooku, čo je príjemné — dá sa to zapnúť len tam, kde to dáva zmysel, a zvyšok nechať tak.

Jedna vec sa však mení aj mimo tohto nastavenia: registrácia webhooku po novom kontroluje oprávnenia doplnku k tým skupinám endpointov, ktoré dáta pre udalosť poskytujú. Ak doplnok k dátam nemá prístup, nedostane ich ani vo webhooku.

Kde sú hranice

Toto je časť, ktorú treba prečítať skôr, než sa začne prepisovať integrácia.

Funguje to len pre create a update. Pri udalostiach typu delete payload nie je — čo dáva zmysel, pretože mazanú entitu už nie je odkiaľ načítať.

Nefunguje to pri hromadných webhookoch. *:massCreate, *:massUpdate ani *:massDelete payload nepodporujú. Práve hromadné operácie pritom bývajú ten prípad, keď integráciu najviac zaťažuje doťahovanie dát — takže najväčšia špička zostáva riešená po starom.

Entity, pri ktorých to funguje:

Najdôležitejšia veta v celej dokumentácii

Ak sa payload v okamihu doručenia nepodarí načítať, notifikácia príde aj tak — len bez poľa payload.

Je to návrh, ktorý dáva zmysel (lepšie doručiť notifikáciu bez dát než ju nedoručiť vôbec), ale má jeden dôsledok: volanie detailného endpointu nesmie z integrácie zmiznúť. Zostáva ako záložná cesta pre prípad, keď payload chýba.

Kto to vezme skratkou v štýle „payload je zapnutý, tak detail už volať nemusíme", vyrobí si chybu, ktorá sa neprejaví v testoch a objaví sa až v prevádzke, v najhoršom možnom momente. Správna implementácia je podmienka: je payload v notifikácii? použi ho. Nie je? zavolaj detail, ako predtým.

A ešte jeden detail k podpisom: Shoptet-Webhook-Signature sa počíta z celého tela notifikácie vrátane payloadu. Metóda výpočtu sa nemení, ale kto si podpis overoval nad inak poskladaným telom, musí to skontrolovať.

Čo to znamená v praxi

Pre integrácie, ktoré staviame a prevádzkujeme, je to užitočná zmena hneď v niekoľkých ohľadoch:

• Menej volaní do Shoptet API. Jedna zmena = jedno doručenie namiesto dvoch operácií. Pri e-shopoch s vysokou frekvenciou zmien je to citeľný úbytok prevádzky.
• Menšie riziko naraziť na limity. Čím menej požiadaviek, tým menšia šanca, že sa integrácia zadrhne na rate limitoch práve v špičke.
• Kratšia cesta od zmeny k spracovaniu. Odpadá jedno kolo dopytu a čakanie na odpoveď, takže sa synchronizácia približuje reálnemu času.
• Menej miest, kde to môže zlyhať. Každé volanie API navyše je ďalšia príležitosť na timeout, chybu alebo zdržanie. Jedna operácia namiesto dvoch znamená jednoduchšie spracovanie aj jednoduchšie hľadanie príčin, keď sa niečo pokazí.

Nejde o novú funkcionalitu — nič, čo doteraz nešlo, zrazu nejde. Je to zjednodušenie cesty, ktorou integrácie už chodia. Čo je pri prevádzkových systémoch zvyčajne cennejšie než nová funkcia.

Čo s tým urobiť

Ak máte nad Shoptetom postavenú integráciu, toto je rozumná postupnosť krokov:

1. Prejdite si, ktoré webhooky skutočne používate a pri ktorých z nich sa po prijatí volá detail entity. To sú kandidáti.
2. Overte, že doplnok má oprávnenia ku skupinám endpointov, ktoré dáta pre danú udalosť poskytujú.
3. Upravte spracovanie na podmienku, nie na predpoklad — payload použi, ak je; inak dotiahni detail. Až potom má zmysel čokoľvek zapínať.
4. Zapnite sendPayload na jednom webhooku a nechajte ho bežať. Nie na všetkých naraz.
5. Nezabudnite na podpis — overuje sa nad celým telom vrátane payloadu.
6. Hromadné operácie nechajte bez zmeny. Payload pri nich nie je a nebude súčasťou tejto zmeny.

Časté otázky

Čo sa v Shoptet API 29. septembra zmenilo? Webhook môže po novom obsahovať pole payload s kompletnými dátami entity. Doteraz notifikácia niesla len informáciu o tom, čo sa zmenilo, a aplikácia si musela dáta dotiahnuť ďalším volaním detailného endpointu.

Ako sa posielanie payloadu zapína? Pri registrácii alebo úprave webhooku sa pridá parameter "sendPayload": "full". Bez neho sa správanie nemení, takže existujúce integrácie bežia ďalej bez zmeny.

Pri ktorých entitách to funguje? Pri brand, category, product, sectionArticle, order, invoice, proformaInvoice, creditNote, deliveryNote, proofPayment, customer, discountCoupon a quantityDiscount. Vždy len pre udalosti typu create a update.

Čo payload nevie? Nepodporuje hromadné webhooky (massCreate, massUpdate, massDelete) ani udalosti typu delete. Pri nich notifikácia príde ako doteraz, bez dát.

Môžeme po nasadení zahodiť volanie detailného endpointu? Nie. Shoptet uvádza, že ak sa payload v okamihu doručenia nepodarí načítať, notifikácia dorazí bez poľa payload. Volanie detailu musí zostať ako záložná cesta.

Mení sa overovanie podpisu webhooku? Spôsob výpočtu zostáva rovnaký, ale podpis sa počíta z celého tela notifikácie vrátane payloadu. Kto si podpis overuje nad orezaným telom, musí to upraviť.

Zhrnutie

• Webhook môže po novom niesť kompletné dáta entity. Zapína sa parametrom "sendPayload": "full" pri konkrétnom webhooku, nič sa nedeje automaticky.
• Platí to pre 13 entít a len pre create a update. Hromadné webhooky a delete udalosti payload nepodporujú.
• Volanie detailného endpointu musí zostať. Keď sa payload nepodarí načítať, notifikácia dorazí bez neho — a integrácia na to musí byť pripravená.

---

Riešite napojenie Shoptetu na ERP, sklad alebo iný systém? Postavíme a prevádzkujeme integrácie nad Shoptet API — od návrhu po dohľad nad prevádzkou: Shoptet na mieru.

Zdroje

• Shoptet Developers: Webhooks with payload in Shoptet API