> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.skaitra.com/api/ivykiai-ir-webhook/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.skaitra.com/_mcp/server.

# Į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

| Tipas                      | Kada                                                           | Reikalinga teisė |
| -------------------------- | -------------------------------------------------------------- | ---------------- |
| `document.received`        | Atkeliavo dokumentas (įkeltas, el. paštu, iš Drive ar per API) | `documents:read` |
| `document.ocr_completed`   | Dokumentas nuskaitytas, jo duomenys paruošti                   | `documents:read` |
| `document.ocr_failed`      | Dokumento nuskaityti nepavyko                                  | `documents:read` |
| `obligation.updated`       | Pasikeitė mėnesio darbo būsena ar atsakingas                   | `work:read`      |
| `task.completed`           | AI užduotis gavo rezultatą                                     | `tasks:read`     |
| `company.updated`          | Pasikeitė įmonės duomenys                                      | `companies:read` |
| `company.settings_updated` | Pasikeitė įmonės nustatymai                                    | `companies:read` |
| `webhook.test`             | Bandomasis įvykis, siunčiamas jūsų prašymu                     | –                |

Įvykio pavidalas:

```json
{
  "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`.

```bash
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.

```bash
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](https://www.standardwebhooks.com/) 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:

```ts
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).

> Kaip sužinoti, kas pasikeitė Skaitroje – užklausomis arba gaunant pranešimus į savo adresą.