Webhooki

Webhooki odbierają zdarzenia w czasie rzeczywistym przez HTTP POST na skonfigurowany przez Ciebie adres URL. Te same zdarzenia są dostępne także przez SSE. Webhooki są skonfigurowane dla każdej organizacji - każda organizacja ma własne webhooki.

ZarządzanieKopiuj link do tej sekcji

Pełne schematy żądań i odpowiedzi znajdziesz w specyfikacji OpenAPI.

Tworzenie webhookaKopiuj link do tej sekcji

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, który przyjmuje żądania POST
• subscribedEventKeys - Tablica kluczy zdarzeń lub ["*"] dla wszystkich zdarzeń. Pełną listę znajdziesz w Tillor w Menu profilu → Dla deweloperów przy Dodaj webhooka → Subskrybowane wydarzenia.

Kilka zdarzeń występuje tak często, że nie można ich wybrać i nie docierają też przez *, na przykład fizyczny stan szlabanów, pisanie w skrzynce odbiorczej, logi kontrolerów i obecność pojazdów. Nie ma ich na poniższej liście. To, które zdarzenia możesz wybrać, zależy też od Twoich uprawnień.

• enabled - true, aby włączyć dostarczanie

Możesz wybrać tylko zdarzenia, do których Twój członek organizacji ma odpowiednie uprawnienie (np. transakcje bankowe dla bankAccountTransaction:*). Wildcard * jest dostępny tylko dla członków z pełnym dostępem (*). Przy nieprawidłowej kombinacji API zwraca błąd. Webhook przekazuje pełny payload wraz z powiązanymi danymi (jak klient przy rezerwacji). Dlatego, aby utworzyć webhook, zmienić jego URL lub zdarzenia albo włączyć go ponownie, musisz mieć też prawo odczytu tych domen.

Payload webhookaKopiuj link do tej sekcji

Każde dostarczenie webhooka to POST z:

Nagłówkami:

• Content-Type: application/json
• X-Webhook-Event-ID - stabilne unikalne ID tego logicznego dostarczenia (ta sama wartość przy ponownych próbach)
• X-Webhook-Signature - podpis HMAC-SHA256 body, format sha256=<hex> (zobacz Weryfikacja podpisu)

Body:

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

Pełne przykłady payloadów znajdziesz w Przykładach.

Weryfikacja podpisuKopiuj link do tej sekcji

Każdy webhook ma własny sekret podpisywania (64 znaki hex, widoczny w tabeli webhooków przez Pokaż sekret podpisywania w Menu profilu → Dla deweloperów). Tillor podpisuje każdy POST tym sekretem, abyś mógł sprawdzić, że żądanie naprawdę pochodzi od Tillor i że body nie zostało zmienione.

Jak podpisuje Tillor:

1. Oblicz HMAC-SHA256(signingSecret, raw_request_body) (hex małymi literami).
2. Wyślij to jako X-Webhook-Signature: sha256=<hex>.

Jak weryfikujesz Ty:

1. Odczytaj surowe body żądania (przed parsowaniem JSON - inaczej hash się nie zgodzi).
2. Sam oblicz HMAC-SHA256(signingSecret, raw_body) w hex.
3. Porównaj z wartością po sha256= z nagłówka X-Webhook-Signature za pomocą porównania 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);
}

Zachowanie dostarczania i ponowne próbyKopiuj link do tej sekcji

• Odpowiedz statusem 2xx, aby potwierdzić sukces.
• Przy nieudanym dostarczeniu (status inny niż 2xx, błąd sieci lub zablokowany cel) Tillor automatycznie ponawia dostarczenie ze stopniowo coraz dłuższymi odstępami. Każda próba używa tego samego payloadu, tego samego podpisu i tego samego ID zdarzenia (idempotentnie).

• Jeśli jedna z prób się powiedzie (2xx) → dostarczenie jest zakończone.
• Jeśli nie powiedzie się też próba 10 (po 24 h) → dostarczenie jest ostatecznie oznaczone jako nieudane i nie jest już ponawiane.
• Jeśli w międzyczasie webhook zostanie wyłączony, Tillor przestaje ponawiać próby.

Powiadomienia przy utrzymujących się błędachKopiuj link do tej sekcji

Jeśli dostarczenia do endpointu webhooka stale się nie udają, Tillor wysyła najwyżej dwa powiadomienia na incydent (na endpoint):

1. Po 5 minutach utrzymujących się błędów - e-mail na adres e-mail organizacji (supportEmail, w przeciwnym razie email) oraz do członków organizacji z uprawnieniami do zmiany ustawień organizacji, a także push (jeśli włączony) dla tych członków. E-mail podaje, od kiedy dostarczenia się nie udają. Daty w e-mailu używają strefy czasowej z Ustawienia > Ogólne (domyślnie Europe/Brussels).
2. Przy ostatecznym niepowodzeniu - ci sami odbiorcy dostają jedno powiadomienie, gdy pierwsze zdarzenie w tym incydencie zostanie po wszystkich próbach ostatecznie oznaczone jako nieudane.

Nie dostajesz powiadomienia dla każdego nieudanego zdarzenia. Gdy wszystkie nieudane dostarczenia dla endpointu zostaną rozwiązane (dostarczone pomyślnie), kolejny incydent zaczyna się od nowa według tych samych reguł.

W Menu profilu → Dla deweloperów tabela webhooków pokazuje dla każdego endpointu zwięzły status dostarczeń (liczby oczekujące na ponowną próbę i ostatecznie nieudane). Kliknij ikonę ℹ, aby zobaczyć szczegóły, w tym pełny komunikat błędu i payload ostatniej próby.

• Ponów próbę dostarczenia nieudanych dostaw (↻): tylko dostawy ostatecznie nieudane dla tego webhooka.
• Wymuś ponowną próbę (⚡): wszystkie oczekujące i ostatecznie nieudane dostawy dla tego webhooka, niezależnie od zaplanowanych czasów oczekiwania. Tillor uruchamia to w tle, aby duże kolejki (np. tysiące zdarzeń) były przetwarzane bezpiecznie.
• Wymuś ponowną próbę wszystkich w prawym górnym rogu obok Dodaj webhooka: to samo dla wszystkich włączonych webhooków w organizacji.

Typy zdarzeńKopiuj link do tej sekcji

Klucze zdarzeń mają format entity:action lub entity:subresource:action. Pełną listę, z uprawnieniem dla każdego zdarzenia i przykładowym payloadem, znajdziesz w indeksie zdarzeń. Ta strona jest generowana z kodu, więc zawsze jest kompletna. Te same klucze znajdziesz w Tillor w Menu profilu → Dla deweloperów przy Dodaj webhooka → Subskrybowane wydarzenia.

Webhooki a SSEKopiuj link do tej sekcji

PowiązaneKopiuj link do tej sekcji

• OpenAPI - Pełna specyfikacja API
• HTTP API - REST API i klucze API
• SSE - Te same zdarzenia przez Server-Sent Events
• Automatyzacje - Wysyłanie własnych wiadomości z automatyzacji