Webhook payload reference
Presná schéma JSON payload-u, ktorý posielame na váš endpoint pri publikovaní článku. Použiteľné pre Next.js, Astro, Remix, SvelteKit, Express, PHP a akýkoľvek HTTP server.
Request
| Method | POST |
| URL | vami zadaná Site URL (napr. https://mojfirma.sk/api/aio-webhook) |
| Timeout | 10 sekúnd |
| Content-Type | application/json |
Headers
| Header | Hodnota | Kedy |
|---|---|---|
| Content-Type | application/json | vždy |
| X-Webhook-Event | article.published | len pri publikovaní |
| X-Webhook-Signature | sha256=<HMAC hex> | len pri publikovaní, ak je secret nastavený |
| Authorization | Bearer <apiKey> | vždy, ak je API key nastavený |
Payload schéma
Top-level polia
| Pole | Typ | Popis |
|---|---|---|
| event | string | „article.published" alebo „test" |
| timestamp | string (ISO 8601) | UTC čas odoslania webhook-u |
| source | string | Vždy „aio-tracking" |
| data | object | Telo článku (chýba pri event="test") |
Polia v data
| Pole | Typ | Popis |
|---|---|---|
| title | string | Hlavný titulok článku (H1) |
| htmlContent | string | Celý obsah článku ako HTML — pripravený na vloženie do <article> |
| excerpt | string | Krátky úryvok (~160 znakov) pre náhľady a OG description |
| coverImageUrlopt | string (URL) | Verejne dostupný URL cover obrázku (1200×630) |
| slug | string | URL-friendly slug bez diakritiky (napr. ai-chatbot-pre-eshop) |
| seoTitle | string | Optimalizovaný titulok pre <title> tag (max 60 znakov) |
| metaDesc | string | Meta description (max 160 znakov) |
| tagsopt | string[] | Pole tagov / kategórií článku |
| schemaMarkupopt | string (JSON) | Pripravený JSON-LD Article schema markup ako string |
Príklady
Production payload (event: „article.published")
{
"event": "article.published",
"timestamp": "2026-05-15T10:00:00.000Z",
"source": "aio-tracking",
"data": {
"title": "Ako využiť AI chatbot v slovenskom eshope",
"htmlContent": "<h1>Úvod</h1><p>AI chatboty pomáhajú...</p>",
"excerpt": "Krátky popis článku pre náhľady a meta description.",
"coverImageUrl": "https://cdn.optimalizaciapreai.sk/cover.jpg",
"slug": "ai-chatbot-pre-eshop",
"seoTitle": "AI chatbot pre eshop — kompletný návod 2026",
"metaDesc": "Ako AI chatbot zvyšuje konverzie v slovenských eshopoch.",
"tags": ["chatbot", "eshop", "ai"],
"schemaMarkup": "{\"@context\":\"https://schema.org\",\"@type\":\"Article\",...}"
}
}Test payload (Test Connection tlačidlo)
{
"event": "test",
"timestamp": "2026-05-15T10:00:00.000Z",
"source": "aio-tracking"
}Test request neobsahuje HMAC podpis ani X-Webhook-Event header.
Vo svojom endpoint-e najprv skontrolujte event === 'test' a vráťte 200 OK — verifikáciu podpisu spustite až pre event === 'article.published'. Vzorové snippety v návode pre Next.js to robia v správnom poradí.
HMAC verifikácia
Ak ste vo wizarde nastavili Webhook Secret, každý payload prichádza so SHA-256 HMAC podpisom v hlavičke x-webhook-signature. Overte ho takto:
import { createHmac, timingSafeEqual } from 'crypto'
const raw = await req.text()
const signature = req.headers.get('x-webhook-signature') || ''
const expected = 'sha256=' + createHmac('sha256', SECRET)
.update(raw)
.digest('hex')
const valid =
signature.length === expected.length &&
timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
if (!valid) throw new Error('Invalid signature')Použite timingSafeEqual
Bežné === porovnanie je zraniteľné na timing attack — útočník vie podľa času odpovede uhádnuť signature znak po znaku.
Očakávaná odpoveď
Váš endpoint by mal odpovedať 200 OK s JSON-om obsahujúcim:
{
"externalId": "ai-chatbot-pre-eshop",
"externalUrl": "https://mojfirma.sk/blog/ai-chatbot-pre-eshop"
}externalId— identifier článku vo vašom systéme (DB ID, slug, atď.). Uložíme si ho pre prípadný update.externalUrl— verejná URL, na ktorej je článok dostupný. Zobrazí sa v dashboarde ako „Publikované na… → otvoriť".
Pri chybe
Vráťte status 4xx alebo 5xx s JSON-om:
{ "error": "human-readable popis chyby" }My zachytíme správu, označíme publikáciu ako neúspešnú a zákazník uvidí chybu v dashboarde.