Shoptet posílá data přímo ve webhooku. Co to mění pro integrace

Shoptet 29. září zapnul u webhooků volitelné odesílání payloadu. Notifikace tak může nově nést rovnou kompletní data entity — objednávky, produktu, zákazníka, faktury a dalších. Pro integrace to znamená, že na jednu změnu stačí jedno doručení místo dvojice „notifikace + dotaz do API".

Zní to jako detail. V provozu integrací, které synchronizují e-shop s ERP, skladem nebo CRM, je to ale jedna z těch změn, které se projeví na stabilitě.

Jak to fungovalo dosud

Model byl jednoduchý a všichni ho znají: Shoptet pošle na váš endpoint notifikaci ve stylu „objednávka 2026000123 byla vytvořena". Notifikace sama o sobě žádná data neobsahuje. Aplikace si je musela dotáhnout — zavolat detailní endpoint objednávky a teprve pak mohla něco zpracovat.

Každá změna na e-shopu tedy stála minimálně dvě síťové operace a jedno volání API navíc. U e-shopu, kde se v sezóně mění ceny a stavy objednávek v řádu tisíců událostí denně, se to sčítá.

Co se změnilo

Notifikace může nově obsahovat pole payload s daty entity:

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

Obsah payload odpovídá tomu, co by vrátil detailní endpoint dané entity — včetně všech parametrů include, které jsou pro něj dostupné. Není to tedy zkrácený výtah, ale ta samá data, pro která se dosud volalo zvlášť.

Jak se to zapíná

Explicitně, při registraci nebo úpravě webhooku, parametrem sendPayload:

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

Nic se neděje samo. Bez tohoto parametru se chování nemění, takže žádná stávající integrace tím nerozbije. Je to opt-in na úrovni jednotlivého webhooku, což je příjemné — dá se to zapnout jen tam, kde to dává smysl, a zbytek nechat být.

Jedna věc se ale mění i mimo tohle nastavení: registrace webhooku nově kontroluje oprávnění doplňku k těm skupinám endpointů, které data pro událost poskytují. Pokud doplněk k datům nemá přístup, nedostane je ani ve webhooku.

Kde jsou hranice

Tohle je část, kterou je potřeba si přečíst dřív, než se začne přepisovat integrace.

Funguje to jen pro create a update. U událostí typu delete payload není — což dává smysl, protože mazanou entitu už není odkud načíst.

Nefunguje to u hromadných webhooků. *:massCreate, *:massUpdate ani *:massDelete payload nepodporují. Právě hromadné operace přitom bývají ten případ, kdy integraci nejvíc zatěžuje dotahování dat — takže největší špička zůstává řešená postaru.

Entity, u kterých to funguje:

Nejdůležitější věta v celé dokumentaci

Pokud se payload v okamžiku doručení nepodaří načíst, notifikace přijde i tak — jen bez pole payload.

To je návrh, který dává smysl (lepší doručit notifikaci bez dat než ji nedoručit vůbec), ale má jeden důsledek: volání detailního endpointu nesmí z integrace zmizet. Zůstává jako záložní cesta pro případ, kdy payload chybí.

Kdo to vezme zkratkou ve stylu „payload je zapnutý, tak detail už volat nemusíme", vyrobí si chybu, která se neprojeví v testech a objeví se až v provozu, v nejhorší možný moment. Správná implementace je podmínka: je payload v notifikaci? použij ho. Není? zavolej detail, jako dřív.

A ještě jeden detail k podpisům: Shoptet-Webhook-Signature se počítá z celého těla notifikace včetně payloadu. Metoda výpočtu se nemění, ale kdo si podpis ověřoval nad jinak poskládaným tělem, musí to zkontrolovat.

Co to znamená v praxi

Pro integrace, které stavíme a provozujeme, je to užitečná změna hned v několika ohledech:

• Méně volání do Shoptet API. Jedna změna = jedno doručení místo dvou operací. U e-shopů s vysokou frekvencí změn je to znatelný úbytek provozu.
• Menší riziko narazit na limity. Čím méně požadavků, tím menší šance, že se integrace zadrhne na rate limitech zrovna ve špičce.
• Kratší cesta od změny ke zpracování. Odpadá jedno kolo dotazu a čekání na odpověď, takže se synchronizace přibližuje reálnému času.
• Méně míst, kde to může selhat. Každé volání API navíc je další příležitost k timeoutu, chybě nebo prodlevě. Jedna operace místo dvou znamená jednodušší zpracování i jednodušší hledání příčin, když se něco pokazí.

Nejde o novou funkcionalitu — nic, co dosud nešlo, najednou nejde. Je to zjednodušení cesty, kterou už integrace chodí. Což je u provozních systémů obvykle cennější než nová funkce.

Co s tím udělat

Pokud máte nad Shoptetem postavenou integraci, tohle je rozumná posloupnost kroků:

1. Projděte si, které webhooky skutečně používáte a u kterých z nich se po přijetí volá detail entity. To jsou kandidáti.
2. Ověřte, že doplněk má oprávnění ke skupinám endpointů, které data pro danou událost poskytují.
3. Upravte zpracování na podmínku, ne na předpoklad — payload použij, pokud je; jinak dotáhni detail. Teprve potom má smysl cokoli zapínat.
4. Zapněte sendPayload na jednom webhooku a nechte ho běžet. Ne na všech najednou.
5. Nezapomeňte na podpis — ověřuje se nad celým tělem včetně payloadu.
6. Hromadné operace nechte beze změny. Payload u nich není a nebude součástí téhle změny.

Časté otázky

Co se v Shoptet API 29. září změnilo? Webhook může nově obsahovat pole payload s kompletními daty entity. Dosud notifikace nesla jen informaci o tom, co se změnilo, a aplikace si musela data dotáhnout dalším voláním detailního endpointu.

Jak se posílání payloadu zapíná? Při registraci nebo úpravě webhooku se přidá parametr "sendPayload": "full". Bez něj se chování nemění, takže stávající integrace běží dál beze změny.

U kterých entit to funguje? U brand, category, product, sectionArticle, order, invoice, proformaInvoice, creditNote, deliveryNote, proofPayment, customer, discountCoupon a quantityDiscount. Vždy jen pro události typu create a update.

Co payload neumí? Nepodporuje hromadné webhooky (massCreate, massUpdate, massDelete) ani události typu delete. U nich notifikace přijde jako dosud, bez dat.

Můžeme po nasazení zahodit volání detailního endpointu? Ne. Shoptet uvádí, že pokud se payload v okamžiku doručení nepodaří načíst, notifikace dorazí bez pole payload. Volání detailu musí zůstat jako záložní cesta.

Mění se ověřování podpisu webhooku? Způsob výpočtu zůstává stejný, ale podpis se počítá z celého těla notifikace včetně payloadu. Kdo si podpis ověřuje nad ořezaným tělem, musí to upravit.

Shrnutí

• Webhook může nově nést kompletní data entity. Zapíná se parametrem "sendPayload": "full" u konkrétního webhooku, nic se neděje automaticky.
• Platí to pro 13 entit a jen pro create a update. Hromadné webhooky a delete události payload nepodporují.
• Volání detailního endpointu musí zůstat. Když se payload nepodaří načíst, notifikace dorazí bez něj — a integrace na to musí být připravená.

---

Řešíte napojení Shoptetu na ERP, sklad nebo jiný systém? Postavíme a provozujeme integrace nad Shoptet API — od návrhu po dohled nad provozem: Shoptet na míru.

Zdroje

• Shoptet Developers: Webhooks with payload in Shoptet API