Webhook

I webhook ricevono eventi in tempo reale tramite HTTP POST su un URL configurato da te. Gli stessi eventi sono disponibili anche tramite SSE. I webhook sono configurati per organizzazione: ogni organizzazione ha i propri webhook.

GestioneCopia il link a questa sezione

Per gli schemi completi di richiesta e risposta vedi la specifica OpenAPI.

Creare un webhookCopia il link a questa sezione

POST /api/orgs/org_abc123/webhooks
Content-Type: application/json
x-api-key: tkn_xxx

{
  "url": "https://jouw-server.com/webhooks/tillor",
  "subscribedEventKeys": ["invoice:created", "invoice:paid", "customer:updated"],
  "enabled": true
}

• url - endpoint HTTPS che accetta richieste POST
• subscribedEventKeys - array di chiavi di evento oppure ["*"] per tutti gli eventi. L'elenco completo si trova in Tillor sotto Menu del profilo → Sviluppatori, in Aggiunga webhook → Eventi iscritti.

Alcuni eventi sono così frequenti che non puoi sceglierli e che non arrivano nemmeno tramite *, come lo stato fisico delle barriere, la digitazione nella inbox, i log del controller e la presenza dei veicoli. Non compaiono nell'elenco qui sotto. Quali eventi puoi scegliere dipende anche dai tuoi permessi.

• enabled - true per attivare la consegna

Puoi scegliere solo eventi per cui il tuo membro dell'organizzazione ha il permesso corretto (ad es. transazioni bancarie per bankAccountTransaction:*). Il carattere jolly * è disponibile solo per i membri con accesso completo (*). Con una combinazione non valida l'API restituisce un errore. Un webhook inoltra il payload completo, con i dati collegati (come il cliente in una prenotazione). Per questo devi poter leggere anche quei domini per creare un webhook, modificarne l'URL o gli eventi, o riattivarlo.

Payload del webhookCopia il link a questa sezione

Ogni consegna di un webhook è una POST con:

Header:

• Content-Type: application/json
• X-Webhook-Event-ID - ID univoco stabile di questa consegna logica (stesso valore nei nuovi tentativi)
• X-Webhook-Signature - firma HMAC-SHA256 del body, formato sha256=<hex> (vedi Verificare la firma)

Body:

{
  "event": "invoice:created",
  "data": {},
  "timestamp": 1735689600000,
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7",
  "triggeredBy": {
    "id": "usr_63x8jp68is",
    "name": "Niels"
  }
}

Vedi gli Esempi per esempi completi di payload.

Verificare la firmaCopia il link a questa sezione

Ogni webhook ha un proprio signing secret (64 caratteri esadecimali, visibile nella tabella dei webhook tramite Mostra la chiave di firma in Menu del profilo → Sviluppatori). Tillor firma ogni POST con quel secret, così puoi verificare che la richiesta provenga davvero da Tillor e che il body non sia stato modificato.

Come firma Tillor:

1. Calcola HMAC-SHA256(signingSecret, raw_request_body) (esadecimale minuscolo).
2. Lo invia come X-Webhook-Signature: sha256=<hex>.

Come verifichi tu:

1. Leggi il body grezzo della richiesta (prima del parsing JSON, altrimenti l'hash non corrisponde).
2. Calcola tu stesso HMAC-SHA256(signingSecret, raw_body) in esadecimale.
3. Confronta con il valore dopo sha256= nell'header X-Webhook-Signature con un confronto constant-time.

import crypto from "node:crypto";

function verifyTillorWebhook(rawBody, headerSignature, signingSecret) {
  const expected = crypto.createHmac("sha256", signingSecret).update(rawBody).digest("hex");
  const received = headerSignature.replace(/^sha256=/, "");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Comportamento di consegna e nuovi tentativiCopia il link a questa sezione

• Rispondi con uno stato 2xx per confermare il successo.
• In caso di consegna fallita (non 2xx, errore di rete o destinazione bloccata) Tillor riprova automaticamente la consegna con intervalli sempre più lunghi. Ogni tentativo riutilizza lo stesso payload, la stessa firma e lo stesso ID evento (idempotente).

• Se uno dei tentativi riesce (2xx) → la consegna è conclusa.
• Se anche il tentativo 10 (dopo 24 ore) fallisce → la consegna viene contrassegnata definitivamente come fallita e non viene più ritentata.
• Se nel frattempo il webhook viene disattivato, Tillor smette di riprovare.

Notifiche in caso di errori persistentiCopia il link a questa sezione

Se le consegne a un endpoint webhook continuano a fallire, Tillor invia al massimo due notifiche per incidente (per endpoint):

1. Dopo 5 minuti di errori persistenti - e-mail all'indirizzo e-mail dell'organizzazione (supportEmail, altrimenti email) e ai membri dell'organizzazione con il diritto di modificare le impostazioni dell'organizzazione, più push (se attivato) per quei membri. L'e-mail indica da quando le consegne falliscono. Le date nell'e-mail usano il fuso orario di Impostazioni > Generale (per impostazione predefinita Europe/Brussels).
2. In caso di fallimento definitivo - gli stessi destinatari ricevono una notifica quando il primo evento di quell'incidente è stato contrassegnato come definitivamente fallito dopo tutti i tentativi.

Non ricevi una notifica per ogni evento fallito. Quando tutte le consegne fallite di un endpoint sono risolte (consegnate con successo), un nuovo incidente ricomincia con le stesse regole.

In Menu del profilo → Sviluppatori la tabella dei webhook mostra per endpoint uno stato di consegna compatto (numero di consegne in attesa di un nuovo tentativo e definitivamente fallite). Clicca sull'icona ℹ per i dettagli, incluso il messaggio di errore completo e il payload del tentativo più recente.

• Riprovi non riuscita (↻): solo le consegne definitivamente fallite di quel webhook.
• Forza il nuovo tentativo (⚡): tutte le consegne in attesa e definitivamente fallite di quel webhook, indipendentemente dai tempi di attesa pianificati. Tillor lo avvia in background, così le code grandi (ad es. migliaia di eventi) vengono elaborate in sicurezza.
• Forza, riprovi tutto in alto a destra accanto a Aggiunga webhook: lo stesso per tutti i webhook attivi dell'organizzazione.

Tipi di eventoCopia il link a questa sezione

Le chiavi degli eventi usano il formato entity:action o entity:subresource:action. L'elenco completo, con il permesso per ogni evento e un esempio di payload, si trova nell'indice degli eventi. Quella pagina viene generata dal codice ed è quindi sempre completa. Le stesse chiavi si trovano in Tillor sotto Menu del profilo → Sviluppatori, in Aggiunga webhook → Eventi iscritti.

Webhook vs SSECopia il link a questa sezione

CorrelatiCopia il link a questa sezione

• OpenAPI - specifica completa dell'API
• API HTTP - API REST e chiavi API
• SSE - Gli stessi eventi tramite Server-Sent Events
• Automazioni - Inviare messaggi propri da un'automazione