Webhookuri

Webhookurile primesc evenimente în timp real prin HTTP POST la un URL configurat de dumneavoastră. Aceleași evenimente sunt disponibile și prin SSE. Webhookurile sunt configurate per organizație - fiecare organizație are propriile webhookuri.

AdministrareCopiază linkul către această secțiune

Consultați specificația OpenAPI pentru schemele complete de cerere și răspuns.

Crearea unui webhookCopiază linkul către această secțiune

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 care acceptă cereri POST
• subscribedEventKeys - listă de chei de evenimente sau ["*"] pentru toate evenimentele. Lista completă o găsiți în Tillor la Meniul de profil → Dezvoltatori, la Adăugați webhook → Evenimente abonate.

Câteva evenimente apar atât de des încât nu le puteți alege și nici nu ajung prin *, precum starea fizică a barierelor, tastarea în inbox, jurnalele controlerelor și prezența vehiculelor. Ele nu se află în lista de mai jos. Ce evenimente puteți alege depinde și de permisiunile dumneavoastră.

• enabled - true pentru a activa livrarea

Puteți alege doar evenimente pentru care membrul organizației are permisiunea corespunzătoare (de ex. tranzacții bancare pentru bankAccountTransaction:*). Wildcardul * este disponibil doar pentru membrii cu acces complet (*). La o combinație nevalidă, API-ul returnează o eroare. Un webhook transmite payloadul complet, cu datele asociate (precum clientul la o rezervare). De aceea trebuie să aveți voie să citiți și acele domenii pentru a crea un webhook, pentru a-i modifica URL-ul sau evenimentele ori pentru a-l reactiva.

Payloadul webhookCopiază linkul către această secțiune

Fiecare livrare webhook este un POST cu:

Antete:

• Content-Type: application/json
• X-Webhook-Event-ID - ID unic și stabil pentru această livrare logică (aceeași valoare la reîncercări)
• X-Webhook-Signature - semnătură HMAC-SHA256 a body-ului, format sha256=<hex> (consultați Verificarea semnăturii)

Body:

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

Consultați Exemple pentru exemple complete de payload.

Verificarea semnăturiiCopiază linkul către această secțiune

Fiecare webhook are propriul secret de semnare (64 de caractere hex, vizibil în tabelul de webhookuri prin Afișați secretul de semnare la Meniul de profil → Dezvoltatori). Tillor semnează fiecare POST cu acest secret, astfel încât să puteți verifica faptul că cererea vine cu adevărat de la Tillor și că body-ul nu a fost modificat.

Cum semnează Tillor:

1. Calculează HMAC-SHA256(signingSecret, raw_request_body) (hex cu litere mici).
2. Trimite rezultatul ca X-Webhook-Signature: sha256=<hex>.

Cum verificați dumneavoastră:

1. Citiți body-ul brut al cererii (înainte de parsarea JSON - altfel hash-ul nu se potrivește).
2. Calculați singur HMAC-SHA256(signingSecret, raw_body) în hex.
3. Comparați cu valoarea de după sha256= din antetul X-Webhook-Signature, printr-o comparație în timp constant.

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);
}

Comportamentul de livrare și reîncercăriCopiază linkul către această secțiune

• Răspundeți cu un status 2xx pentru a confirma succesul.
• La o livrare eșuată (non-2xx, eroare de rețea sau destinație blocată), Tillor reîncearcă automat livrarea, cu pauze din ce în ce mai lungi. Fiecare încercare reutilizează același payload, aceeași semnătură și același ID de eveniment (idempotent).

• Dacă una dintre încercări reușește (2xx) → livrarea este încheiată.
• Dacă nici încercarea 10 (după 24 de ore) nu reușește → livrarea este marcată definitiv ca eșuată și nu mai este reîncercată.
• Dacă webhookul este între timp dezactivat, Tillor nu mai reîncearcă.

Notificări în caz de erori persistenteCopiază linkul către această secțiune

Dacă livrările către un endpoint webhook continuă să eșueze, Tillor trimite cel mult două notificări per incident (per endpoint):

1. După 5 minute de erori persistente - e-mail către adresa de e-mail a organizației (supportEmail, altfel email) și către membrii organizației cu drepturi de a modifica setările organizației, plus push (dacă este activat) pentru acești membri. E-mailul menționează de când eșuează livrările. Datele din e-mail folosesc fusul orar din Setări > General (implicit Europe/Brussels).
2. La eșecul definitiv - aceiași destinatari primesc o singură notificare atunci când primul eveniment din acel incident este marcat definitiv ca eșuat după toate încercările.

Nu primiți o notificare pentru fiecare eveniment eșuat. Imediat ce toate livrările eșuate pentru un endpoint sunt rezolvate (livrate cu succes), un incident următor pornește din nou cu aceleași reguli.

La Meniul de profil → Dezvoltatori, tabelul de webhookuri afișează pentru fiecare endpoint o stare compactă a livrărilor (numărul celor care așteaptă reîncercarea și al celor eșuate definitiv). Faceți clic pe pictograma ℹ pentru detalii, inclusiv mesajul de eroare complet și payloadul ultimei încercări.

• Reîncercați livrările eșuate (↻): doar livrările eșuate definitiv pentru acel webhook.
• Forțați reîncercarea (⚡): toate livrările în așteptare și cele eșuate definitiv pentru acel webhook, indiferent de timpii de așteptare planificați. Tillor pornește acest lucru în fundal, astfel încât cozile mari (de ex. mii de evenimente) să fie prelucrate în siguranță.
• Forțați reîncercarea tuturor, în dreapta sus, lângă Adăugați webhook: același lucru pentru toate webhookurile activate din organizație.

Tipuri de evenimenteCopiază linkul către această secțiune

Cheile evenimentelor folosesc formatul entity:action sau entity:subresource:action. Lista completă, cu permisiunea pentru fiecare eveniment și un exemplu de payload, se află în Indexul de evenimente. Pagina este generată din cod și este deci mereu completă. Aceleași chei se află în Tillor la Meniul de profil → Dezvoltatori, la Adăugați webhook → Evenimente abonate.

Webhookuri vs SSECopiază linkul către această secțiune

Legate de acest subiectCopiază linkul către această secțiune

• OpenAPI - specificația completă a API-ului
• API HTTP - API REST și chei API
• SSE - aceleași evenimente prin Server-Sent Events
• Automatizări - trimiteți mesaje proprii dintr-o automatizare