Webhooks

Webhooks erhalten Echtzeit-Events per HTTP POST an eine von Ihnen konfigurierte URL. Dieselben Events sind auch über SSE verfügbar. Webhooks werden pro Organisation konfiguriert - jede Organisation hat ihre eigenen Webhooks.

VerwaltungLink zu diesem Abschnitt kopieren

Die vollständigen Request- und Response-Schemas finden Sie in der OpenAPI-Spezifikation.

Webhook anlegenLink zu diesem Abschnitt kopieren

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 - HTTPS-Endpunkt, der POST-Requests akzeptiert
• subscribedEventKeys - Array von Event-Keys oder ["*"] für alle Events. Die vollständige Liste finden Sie in Tillor unter Profilmenü → Entwickler bei Webhook hinzufügen → Abonnierte Ereignisse.

Einige Events kommen so häufig vor, dass Sie sie nicht auswählen können und dass sie auch nicht über * ankommen, etwa der physische Zustand von Schranken, das Tippen im Posteingang, Controller-Logs und Fahrzeuganwesenheit. Diese stehen nicht in der Liste unten. Welche Events Sie auswählen können, hängt auch von Ihren Berechtigungen ab.

• enabled - true, um die Zustellung einzuschalten

Sie dürfen nur Events auswählen, für die Ihr Organisationsmitglied die passende Berechtigung hat (z. B. Banktransaktionen für bankAccountTransaction:*). Der Wildcard * ist nur für Mitglieder mit vollem Zugriff (*) verfügbar. Bei einer ungültigen Kombination gibt die API eine Fehlermeldung zurück. Ein Webhook leitet die vollständige Payload weiter, mit den verknüpften Daten (wie dem Kunden bei einer Reservierung). Daher müssen Sie auch diese Bereiche lesen dürfen, um einen Webhook anzulegen, die URL oder Events zu ändern oder ihn wieder einzuschalten.

Webhook-PayloadLink zu diesem Abschnitt kopieren

Jede Webhook-Zustellung ist ein POST mit:

Header:

• Content-Type: application/json
• X-Webhook-Event-ID - stabile eindeutige ID dieser logischen Zustellung (gleicher Wert bei Retries)
• X-Webhook-Signature - HMAC-SHA256-Signatur des Body, Format sha256=<hex> (siehe Signatur verifizieren)

Body:

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

Vollständige Payload-Beispiele finden Sie unter Beispiele.

Signatur verifizierenLink zu diesem Abschnitt kopieren

Jeder Webhook hat ein eigenes Signing Secret (64 Hex-Zeichen, in der Webhook-Tabelle über Signaturgeheimnis anzeigen unter Profilmenü → Entwickler sichtbar). Tillor signiert jeden POST mit diesem Secret, damit Sie prüfen können, dass die Anfrage wirklich von Tillor kommt und der Body nicht verändert wurde.

So signiert Tillor:

1. Berechnen Sie HMAC-SHA256(signingSecret, raw_request_body) (Hex in Kleinbuchstaben).
2. Senden Sie das als X-Webhook-Signature: sha256=<hex>.

So verifizieren Sie:

1. Lesen Sie den rohen Request-Body (vor dem JSON-Parsen - sonst passt der Hash nicht).
2. Berechnen Sie selbst HMAC-SHA256(signingSecret, raw_body) in Hex.
3. Vergleichen Sie mit dem Wert hinter sha256= aus dem Header X-Webhook-Signature mit einem Constant-Time-Vergleich.

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

Zustellverhalten und RetriesLink zu diesem Abschnitt kopieren

• Antworten Sie mit einem 2xx-Status, um den Erfolg zu bestätigen.
• Bei einer fehlgeschlagenen Zustellung (nicht-2xx, Netzwerkfehler oder blockiertes Ziel) versucht Tillor die Zustellung automatisch erneut, mit immer längeren Abständen. Jeder Versuch verwendet dieselbe Payload, dieselbe Signatur und dieselbe Event-ID (idempotent).

• Gelingt einer der Versuche (2xx) → die Zustellung ist abgeschlossen.
• Gelingt auch Versuch 10 (nach 24 Std.) nicht → die Zustellung wird endgültig als fehlgeschlagen markiert und nicht weiter versucht.
• Wird der Webhook zwischenzeitlich ausgeschaltet, hört Tillor mit den erneuten Versuchen auf.

Benachrichtigungen bei anhaltenden FehlernLink zu diesem Abschnitt kopieren

Schlagen Zustellungen an einen Webhook-Endpunkt weiter fehl, sendet Tillor höchstens zwei Benachrichtigungen pro Vorfall (pro Endpunkt):

1. Nach 5 Minuten anhaltender Fehler - E-Mail an die E-Mail-Adresse der Organisation (supportEmail, sonst email) und an Organisationsmitglieder mit Rechten zum Ändern der Organisationseinstellungen, plus Push (falls aktiviert) für diese Mitglieder. Die E-Mail nennt, seit wann die Zustellungen fehlschlagen. Datumsangaben in der E-Mail verwenden die Zeitzone aus Einstellungen > Allgemein (Standard Europe/Brussels).
2. Bei endgültigem Fehlschlag - dieselben Empfänger erhalten eine Benachrichtigung, wenn das erste Event in diesem Vorfall nach allen Versuchen endgültig als fehlgeschlagen markiert wurde.

Sie erhalten keine Benachrichtigung pro fehlgeschlagenem Event. Sobald alle fehlgeschlagenen Zustellungen für einen Endpunkt behoben sind (erfolgreich zugestellt), beginnt ein nächster Vorfall erneut mit denselben Regeln.

Unter Profilmenü → Entwickler zeigt die Webhook-Tabelle pro Endpunkt einen kompakten Zustellstatus (Anzahl wartend auf erneuten Versuch und endgültig fehlgeschlagen). Klicken Sie auf das ℹ-Symbol für Details, einschließlich der vollständigen Fehlermeldung und der Payload des letzten Versuchs.

• Fehlgeschlagene erneut versuchen (↻): nur endgültig fehlgeschlagene Zustellungen für diesen Webhook.
• Erneuten Versuch erzwingen (⚡): alle wartenden und endgültig fehlgeschlagenen Zustellungen für diesen Webhook, unabhängig von geplanten Wartezeiten. Tillor startet dies im Hintergrund, damit große Warteschlangen (z. B. Tausende Events) sicher verarbeitet werden.
• Alle erzwingen oben rechts neben Webhook hinzufügen: dasselbe für alle eingeschalteten Webhooks der Organisation.

Event-TypenLink zu diesem Abschnitt kopieren

Event-Keys verwenden das Format entity:action oder entity:subresource:action. Die vollständige Liste, mit der Berechtigung pro Event und einer Beispiel-Payload, steht im Event-Index. Diese Seite wird aus dem Code generiert und ist daher immer vollständig. Dieselben Keys stehen in Tillor unter Profilmenü → Entwickler bei Webhook hinzufügen → Abonnierte Ereignisse.

Webhooks vs. SSELink zu diesem Abschnitt kopieren

VerwandtLink zu diesem Abschnitt kopieren

• OpenAPI - Vollständige API-Spezifikation
• HTTP API - REST API und API-Schlüssel
• SSE - Dieselben Events über Server-Sent Events
• Automatisierungen - Eigene Nachrichten aus einer Automatisierung versenden