Įvykiai ir webhook

Skaitra registruoja įvykius: atkeliavo dokumentas, baigtas nuskaitymas, pasikeitė mėnesio darbo būsena ir pan. Juos galite gauti dviem būdais:

• užklausomis – periodiškai kviesti GET /events;
• webhook – Skaitra pati siunčia įvykius į jūsų https:// adresą.

Abiem atvejais matote tik tų įmonių įvykius, prie kurių raktas turi prieigą, ir tik tuos, kuriems raktas turi teisę.

Įvykių tipai

Įvykio pavidalas:

{
  "id": "evt_...",
  "type": "document.received",
  "createdAt": "2026-10-04T08:15:00.000Z",
  "companyId": "...",
  "subject": { "type": "document", "id": "..." },
  "data": {}
}

Įvykių skaitymas užklausomis

GET /events grąžina įvykius nuo seniausio. Kitą kartą perduokite gautą nextCursor kaip after – gausite tik naujus įvykius. Jei naujų nėra, nextCursor lieka toks pat. Galite filtruoti pagal type ir companyId. Reikia teisės events:read.

curl "https://jusu-agentura.skaitra.com/api/v1/events?after=..." \
  -H "Authorization: Bearer skt_..."

Webhook

Webhook adresai tvarkomi per API (teisė webhooks:manage); programoje jų nustatymo kol kas nėra. Adresas priklauso rakto prieigai.

curl -X POST https://jusu-agentura.skaitra.com/api/v1/webhook-endpoints \
  -H "Authorization: Bearer skt_..." \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.lt/skaitra-webhook", "eventTypes": ["document.ocr_completed"] }'

• eventTypes: ["*"] – visi įvykiai, kuriuos raktas gali matyti.
• Atsakyme gausite secret (whsec_...) – parašų tikrinimo raktą. Jis parodomas tik vieną kartą.
• POST /webhook-endpoints/{id}/test išsiunčia webhook.test įvykį ir parodo, kaip atsakė jūsų adresas.
• GET /webhook-endpoints/{id}/deliveries rodo pristatymus ir klaidas.
• PATCH su enabled: false laikinai sustabdo siuntimą, DELETE – pašalina adresą.

Pristatymas ir kartojimas

• Įvykis siunčiamas POST užklausa su JSON turiniu (įvykio pavidalas – aukščiau).
• Pristatymas sėkmingas, jei per 10 sekundžių atsakote 2xx. Peradresavimai nesekami.
• Nepavykus, siuntimas kartojamas po 1, 5 ir 30 minučių, po 2, 6, 12 ir 24 valandų. Po paskutinio bandymo pristatymas pažymimas nepavykusiu.
• Tas pats įvykis gali atkeliauti daugiau nei kartą. Įvykio id nesikeičia, todėl pasikartojimus atpažinsite pagal jį.

Parašo tikrinimas

Užklausos pasirašomos pagal Standard Webhooks specifikaciją. Antraštės:

• webhook-id – įvykio id;
• webhook-timestamp – siuntimo laikas (Unix sekundės);
• webhook-signature – v1, ir HMAC-SHA256 parašas (base64).

Parašas skaičiuojamas iš webhook-id.webhook-timestamp.turinys, raktas – secret be whsec_ priešdėlio, iškoduotas iš base64. Galite naudoti bet kurią Standard Webhooks biblioteką arba patikrinti patys:

import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret: string, headers: Headers, body: string): boolean {
  const id = headers.get("webhook-id") ?? "";
  const timestamp = headers.get("webhook-timestamp") ?? "";
  const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${body}`).digest("base64");
  return (headers.get("webhook-signature") ?? "").split(" ").some((part) => {
    const signature = part.replace(/^v1,/, "");
    return signature.length === expected.length && timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  });
}

Tikrinkite ir webhook-timestamp: atmeskite per senus pranešimus (pavyzdžiui, senesnius nei 5 minutės).