Webhooki

Ko se pri opazovanem subjektu na seznamih FURS kaj spremeni, na vaš URL pošljemo podpisan POST po specifikaciji Standard Webhooks. Webhooki so na voljo na paketu Starter in višjih, ključ potrebuje obseg webhooks. Dostave ne porabijo enot.

Končna točka

curl -X POST https://api.maticna.si/v1/webhook-endpoints \
  -H "Authorization: Bearer $MATICNA_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://erp.example.si/hooks/maticna", "event_types": ["deactivated", "vat_deregistered", "vat_revoked"]}'

Odgovor vsebuje secret (whsec_…). Prikažemo ga samo enkrat; shranite ga med skrivnosti. Pri nas je shranjen šifriran, kasneje vidite le zadnje štiri znake (secret_hint). Če ga izgubite ali ga želite zamenjati, ga zamenjajte.

• url mora biti javno dosegljiv https:// naslov brez uporabniškega imena in gesla. Naslovov v zasebnih omrežjih, localhost in naslovov IP, ki niso javni, ne sprejmemo (422 invalid_webhook_url); preverimo jih tudi ob vsaki dostavi, po razrešitvi DNS.
• event_types omeji dogodke na izbrane vrste sprememb (created, updated, deactivated, reactivated, vat_registered, vat_deregistered, vat_revoked, suppressed); prazen seznam pomeni vse.
• Na organizacijo je največ 10 končnih točk (403 webhook_endpoint_limit_reached).
• GET, PATCH (url, description, event_types, enabled) in DELETE /v1/webhook-endpoints/{id}.
• POST /v1/webhook-endpoints/{id}/test v roku približno ene minute pošlje podpisan dogodek webhook.test.
• POST /v1/webhook-endpoints/{id}/roll-secret ustvari novo skrivnost (glejte Zamenjava skrivnosti).

Dogodek

POST /hooks/maticna HTTP/1.1
Content-Type: application/json
User-Agent: maticna-webhooks/1.0 (+https://maticna.si/docs/webhooks)
webhook-id: msg_6c2c2f7f0d0a4f6c9d7b2e1a0b3c4d5e
webhook-timestamp: 1792470000
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{"type":"entity.vat_deregistered","timestamp":"2026-10-20T06:42:05.000Z","data":{"object":"change","id":"chg_48214","seq":48214,"change_type":"vat_deregistered","tax_number":"19000013", "…": "…"}}

type je entity.<change_type>, data pa objekt change, enak kot v viru sprememb (zavezanec, ki je v celoti umaknjen iz javnih seznamov, pride le z identifikatorji in redacted: true). Dogodek pošljemo za vsako spremembo opazovane davčne številke, ki jo zaznamo po nastanku končne točke.

Preverjanje podpisa (Node.js)

Podpis je HMAC-SHA256 nad {webhook-id}.{webhook-timestamp}.{surovo telo}, s ključem iz base64 dela skrivnosti za whsec_. Preverite ga nad surovim telesom (pred JSON.parse), časovni žig pa naj ne bo starejši od 5 minut:

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyMaticnaWebhook(secret, headers, rawBody) {
  const id = headers['webhook-id'];
  const ts = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];
  if (!id || !ts || !signatures) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // ponovljena ali stara zahteva
  const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
  const expected = createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest();
  return signatures.split(' ').some((s) => {
    const [version, sig] = s.split(',');
    const got = Buffer.from(sig ?? '', 'base64');
    return version === 'v1' && got.length === expected.length && timingSafeEqual(got, expected);
  });
}

// Express: telo potrebujete nespremenjeno
app.post('/hooks/maticna', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyMaticnaWebhook(process.env.MATICNA_WEBHOOK_SECRET, req.headers, req.body.toString('utf8'))) return res.sendStatus(400);
  const event = JSON.parse(req.body);
  queue.add(event); // obdelajte asinhrono
  res.sendStatus(204);
});

Uradne knjižnice Standard Webhooks (npr. standardwebhooks za Node, Python, PHP, Go) preverijo isti podpis.

Zamenjava skrivnosti

curl -X POST https://api.maticna.si/v1/webhook-endpoints/$ID/roll-secret \
  -H "Authorization: Bearer $MATICNA_KEY" -H "Content-Type: application/json" \
  -d '{"grace_period_hours": 24}'

Odgovor vsebuje novo skrivnost secret (spet samo enkrat) in previous_secret_expires_at. Nova skrivnost velja takoj, tudi za ponovne poskuse. Stara ostane veljavna še grace_period_hours ur (privzeto 24, največ 168): v tem času ima vsak dogodek v glavi dva podpisa, webhook-signature: v1,<z novo> v1,<s staro>. Zgornja funkcija in knjižnice Standard Webhooks sprejmejo dogodek, če se ujema katerikoli podpis, zato strežnik med prehodom deluje s staro ali z novo skrivnostjo. Novo skrivnost nastavite pred iztekom; po njem podpisujemo samo z novo.

• grace_period_hours: 0 staro skrivnost umakne takoj (npr. če je ušla).
• Ponovna zamenjava med prehodom takoj umakne starejšo skrivnost; hkrati veljata največ dve.
• Brez telesa zahteve velja privzetih 24 ur. Tudi gumb »Zamenjaj skrivnost« na nadzorni plošči uporablja 24 ur.

Dostava in ponovni poskusi

• Uspeh je vsak odgovor 2xx v 10 sekundah. Preusmeritev (3xx) ni uspeh, ker preusmeritvam ne sledimo.
• Neuspešno dostavo ponovimo po 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h in 24 h (±10 %), skupno približno 3 dni. Vsi poskusi imajo isti webhook-id: po njem odstranite podvojene dogodke.
• Vrstni red dogodkov ni zagotovljen; uredite jih po data.seq.
• Po 20 zaporednih neuspelih poskusih končno točko onemogočimo (enabled: false, disabled_reason: consecutive_failures). Ko jo popravite, jo znova omogočite s PATCH {"enabled": true}; dogodkov iz obdobja, ko je bila onemogočena, ne pošljemo znova (preberite jih iz zgodovine).
• Odgovorite hitro (204) in dogodek obdelajte v ozadju.
• Webhooki so del paketa Starter in višjih. Če organizacija preide na paket brez webhookov, njene končne točke izklopimo (enabled: false, disabled_reason: plan_downgraded), a jih ne izbrišemo. Dostave, ki še čakajo, se končajo kot neuspešne (plan does not include webhooks: delivery withdrawn) in jih ne pošljemo pozneje. Po nadgradnji končne točke spet vklopimo sami; dogodkov iz vmesnega obdobja ne pošljemo znova. Končno točko, ki ste jo v tem času izklopili sami (PATCH {"enabled": false}), pustimo izklopljeno.