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.

EndpointLink naar deze sectie kopiëren

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

AuthenticatieLink naar deze sectie kopiëren

SSE gebruikt dezelfde authenticatie als andere API-endpoints:

• x-api-key - Jouw API-sleutel

Het organisatie-ID staat in het pad van de URL.

Event-filteringLink naar deze sectie kopiëren

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 de Event-index voor alle events, de permissie per event en een voorbeeld-payload.

Een paar events staan op een eigen kanaal (controller-logs en controller-I/O). Die ontvang je alleen met ?channel=controller-logs of ?channel=controller-io; de Event-index vermeldt het kanaal.

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

Gekoppelde gegevens uit een ander domein volgen dezelfde regels als de API: zonder customers:read komt een reservation:updated binnen met customer: null, zonder payments:read een invoice:paid met payment: null. Een lijst wordt dan [].

Event-formaatLink naar deze sectie kopiëren

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.jsLink naar deze sectie kopiëren

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,
    "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: cURLLink naar deze sectie kopiëren

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

HerverbindingLink naar deze sectie kopiëren

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

GerelateerdLink naar deze sectie kopiëren

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