Server-Sent Events (SSE)

SSE biedt een langlopende stream van dezelfde events die webhooks ontvangen. Gebruik SSE wanneer je een persistente verbinding prefereert boven HTTP-callbacks.

Endpoint

GET /api/orgs/:orgId/realtime/subscribe

Authenticatie

SSE gebruikt dezelfde authenticatie als andere API-endpoints:

• x-api-key - Jouw API-sleutel
• X-Tillor-Org-Id - Organisatie-ID (moet overeenkomen met het pad)

Event-filtering

Gebruik de events query-parameter om te filteren op event type:

GET /api/orgs/:orgId/realtime/subscribe?events=invoice:created&events=invoice:paid

Gebruik events=* om alle events te ontvangen (zelfde als parameter weglaten).

Zie Event types voor de volledige lijst.

Tillor levert alleen events waarvoor het ingelogde organisatielid permissie heeft. Zonder bank-transfers:read (of sync) krijg je bijvoorbeeld geen bankAccountTransaction:* events, ook niet als je geen events-filter meestuurt.

Event-formaat

De payload heeft dezelfde structuur als webhook-leveringen:

In de SSE-stream staat dit JSON-object op de data:-regel; de event key staat ook op de event:-regel. Zie SSE-voorbeelden voor een wire-voorbeeld.

Voorbeeld: Node.js

const orgId = "org_abc123";
const apiKey = "tkn_xxx";

const url = `https://app.tillor.eu/api/orgs/${orgId}/realtime/subscribe?events=invoice:created&events=customer:updated`;

const response = await fetch(url, {
  headers: {
    "x-api-key": apiKey,
    "X-Tillor-Org-Id": orgId,
    "Accept": "text/event-stream",
  },
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const chunk = decoder.decode(value, { stream: true });
  for (const line of chunk.split("\n")) {
    if (line.startsWith("data: ")) {
      const payload = JSON.parse(line.slice(6));
      console.log(payload.event, payload.data);
    }
  }
}

Voorbeeld: cURL

curl -N -H "x-api-key: tkn_xxx" \
     -H "X-Tillor-Org-Id: org_abc123" \
     -H "Accept: text/event-stream" \
     "https://app.tillor.eu/api/orgs/org_abc123/realtime/subscribe"

Herverbinding

Als de verbinding verbreekt, herverbind met dezelfde URL en headers. De stream ondersteunt geen resumption; je ontvangt alleen nieuwe events na herverbinden.

Gerelateerd

• OpenAPI - Volledige API-specificatie
• HTTP API - API-sleutels en authenticatie
• Webhooks - Zelfde events via HTTP POST
• Voorbeelden - Code- en payload-voorbeelden