Server-Sent Events (SSE)
Ricevi eventi in tempo reale tramite una connessione di lunga durata
Ultimo aggiornamento il
SSE offre uno stream di lunga durata degli stessi eventi che ricevono i webhook. Usa SSE quando preferisci una connessione persistente alle callback HTTP.
Endpoint
GET /api/orgs/:orgId/realtime/subscribeAutenticazione
SSE usa la stessa autenticazione degli altri endpoint API:
- x-api-key - la tua chiave API
L'ID dell'organizzazione è nel percorso dell'URL.
Filtro degli eventi
Usa il parametro di query events per filtrare per tipo di evento:
GET /api/orgs/:orgId/realtime/subscribe?events=invoice:created&events=invoice:paidUsa events=* per ricevere tutti gli eventi (come omettere il parametro).
Nell'indice degli eventi trovi tutti gli eventi, il permesso per ogni evento e un esempio di payload.
Alcuni eventi hanno un canale proprio (log del controller e I/O del controller). Li ricevi solo con ?channel=controller-logs o ?channel=controller-io; l'indice degli eventi indica il canale.
Tillor consegna solo gli eventi per cui il membro dell'organizzazione connesso ha il permesso. Senza bank-transactions:read (o sync) non ricevi per esempio gli eventi bankAccountTransaction:*, nemmeno se non invii nessun filtro events.
I dati collegati di un altro dominio seguono le stesse regole dell'API: senza customers:read arriva un reservation:updated con customer: null, senza payments:read un invoice:paid con payment: null. Un elenco diventa allora [].
Formato dell'evento
Il payload ha la stessa struttura delle consegne dei webhook:
| Campo | Tipo | Descrizione |
|---|---|---|
event | string | Chiave dell'evento (ad es. invoice:created) |
data | object | Payload specifico dell'evento |
timestamp | number | Unix timestamp (ms) del momento in cui l'evento è stato emesso |
traceId | string | ID di trace OpenTelemetry dell'azione Tillor che ha causato questo evento (come per i webhook) |
spanId | string (facoltativo) | Span all'interno di quella trace |
Nello stream SSE questo oggetto JSON si trova sulla riga data:; la chiave dell'evento compare anche sulla riga event:. Vedi gli esempi SSE per un esempio wire.
Esempio: 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,
"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);
}
}
}Esempio: cURL
curl -N -H "x-api-key: tkn_xxx" \
-H "Accept: text/event-stream" \
"https://app.tillor.eu/api/orgs/org_abc123/realtime/subscribe"Riconnessione
Se la connessione si interrompe, riconnettiti con lo stesso URL e gli stessi header. Lo stream non supporta la ripresa: dopo la riconnessione ricevi solo i nuovi eventi.