Webhooky

​

Kedy webhooky použiť

• keď potrebujete reagovať na vytvorenie, úpravu alebo zmazanie bez toho, aby ste stav zmien stavali na periodickom dotazovaní,
• keď si chcete lokálnu cache alebo downstream systém synchronizovať len pri reálnej zmene,
• keď potrebujete oddeliť prijatie udalosti od následného načítania detailu resource-u.

​

Správa odberov

• hodnotu plainTextSecret si musíte bezpečne uložiť pri create alebo rotate odpovedi,
• zmena url ani subscribedEvents secret automaticky nerotuje,
• isActive = false historické záznamy nevypína, len zastaví nové pokusy o doručenie.

​

Požiadavky na endpoint

• url musí používať https://,
• url nesmie obsahovať používateľské meno ani heslo,
• hostname sa musí resolvnuť na verejnú IP adresu,
• localhost, .local, privátne rozsahy, loopback, link-local a iné rezervované adresy backend odmietne.

​

Payload doručenia

{
  "id": "7f4d1861-9f6a-4fa8-a8a7-f335d7a8d515",
  "type": "invoices.updated",
  "occurredAt": "2026-03-18T15:04:05Z",
  "resource": {
    "type": "invoice",
    "id": 301
  }
}

​

Význam polí

• verziu API,
• absolútnu ani relatívnu URL na resource,
• plný snapshot resource-u,
• vnorené lookupy alebo vnorené obchodné objekty.

​

Delivery headery

​

Overenie podpisu

1. skontrolujte, že request obsahuje všetky webhook headery,
2. skontrolujte, že webhook-timestamp nie je príliš starý alebo príliš ďaleko v budúcnosti,
3. vypočítajte HMAC SHA-256 nad raw request body a porovnajte ho v constant-time režime,
4. deduplikujte podľa webhook-id, aby ste vedeli bezpečne spracovať opakované doručenie.

​

Odporúčaný flow

​

Pseudokód

rawBody = read_raw_request_body()
webhookId = header("webhook-id")
timestamp = integer(header("webhook-timestamp"))
providedSignature = header("webhook-signature")

if webhookId is missing or timestamp is missing or providedSignature is missing:
    return 400

if abs(current_unix_time() - timestamp) > 300:
    return 401

expectedSignature = hmac_sha256(rawBody, webhookSecret)

if not constant_time_equals(expectedSignature, providedSignature):
    return 401

if webhook_id_exists_in_dedup_store(webhookId):
    return 204

store_webhook_id(webhookId)
enqueue_fetch_job(parse_json(rawBody))

return 204

​

JavaScript / Node.js-like príklad

import crypto from 'node:crypto';

export async function handleFintoroWebhook(req, res) {
  // `req.rawBody` musí obsahovať pôvodný raw request body pred JSON parsingom.
  const rawBody = req.rawBody.toString('utf8');
  const webhookId = req.get('webhook-id');
  const timestamp = Number(req.get('webhook-timestamp'));
  const providedSignature = req.get('webhook-signature');

  if (!webhookId || !timestamp || !providedSignature) {
    return res.status(400).json({ error: 'Missing webhook headers.' });
  }

  if (!isFreshWebhookTimestamp(timestamp)) {
    return res.sendStatus(401);
  }

  if (!isValidWebhookSignature(rawBody, providedSignature, process.env.FINTORO_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }

  if (await hasProcessedWebhook(webhookId)) {
    return res.sendStatus(204);
  }

  const event = JSON.parse(rawBody);

  await storeWebhookId(webhookId);
  await enqueueFetchWebhookResourceDetail({
    webhookId,
    eventType: event.type,
    resourceType: event.resource.type,
    resourceId: event.resource.id,
    companyId: event.company.id,
  });

  return res.sendStatus(204);
}

function isFreshWebhookTimestamp(timestamp) {
  return Math.abs(Math.floor(Date.now() / 1000) - timestamp) <= 300;
}

function isValidWebhookSignature(rawBody, providedSignature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  if (expectedSignature.length !== providedSignature.length) {
    return false;
  }

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'utf8'),
    Buffer.from(providedSignature, 'utf8'),
  );
}

​

Ako odpovedať na delivery

• Vráťte 2xx až keď ste request bezpečne prijali, overili a uložili na ďalšie spracovanie.
• Ak signature alebo timestamp nesedia, vráťte 401 alebo inú vlastnú autentifikačnú chybu podľa politiky prijímača webhookov.
• Pri dočasnom downstream probléme vráťte non-2xx, ak chcete, aby systém webhook zopakoval.
• Ak request prijmete, ale ešte len zaraďujete interné spracovanie do fronty, 204 No Content je úplne v poriadku.

• idempotentný,
• odolný voči duplicitám,
• schopný vrátiť 2xx aj pri znovu doručenom už spracovanom webhook-id.

​

Mechanizmus opakovania

• prijímač webhookov vráti non-2xx HTTP status,
• request timeoutne,
• nastane sieťová chyba pri odoslaní.
• endpoint pri predodovacej kontrole už neprejde bezpečnostnou validáciou URL, DNS a IP adresy.

• nepredpokladať exactly-once delivery,
• rátať s tým, že ten istý webhook-id môže prísť opakovane,
• odpovedať rýchlo a ťažšiu logiku delegovať do internej fronty,
• vracať non-2xx len vtedy, keď naozaj chcete, aby Fintoro doručenie zopakovalo.

​

Thin payload a následné načítanie detailu

1. prijmite webhook a overte podpis,
2. deduplikujte podľa webhook-id,
3. podľa type a resource určite, ktorý endpoint detailu potrebujete,
4. detail si načítajte z Fintoro API vo verzii, ktorú používa Vaša integrácia,
5. business logiku robte až nad načítaným detailom.

• clients.updated + resource.id = 42 → GET /clients/42
• invoices.created + resource.id = 301 → GET /invoices/301
• warehouse-outbound-receipts.deleted + resource.id = 88 → ak už detail neexistuje, spracujte delete lokálne len podľa payloadu eventu

​

Dostupné eventy

​

Master data

​

CRM

​

Sklady a katalóg

​

Doklady

​

Praktické odporúčania pre produkciu

• nepúšťajte ťažkú business logiku priamo vo vlákne HTTP requestu prijímača webhookov,
• raw payload aj webhook-id si ukladajte pred ďalším spracovaním,
• secret rotujte kontrolovane a s plánom výmeny na strane prijímača webhookov,
• sledujte retry vzory a opakované non-2xx odpovede ako indikátor incidentu na strane prijímača webhookov,
• logujte si webhook-id, type, resource.type, resource.id a X-Request-Id z následného načítania detailu,
• pri delete eventoch sa nespoliehajte na to, že detail endpoint ešte stále vráti resource.

​

Súvisiace sekcie

• Začíname
• Autentifikácia
• Konvencie API
• Chyby a idempotencia
• Webhook API referencia