Webhooks

Ein Webhook meldet Buchungen, Mitgliederwechsel oder Platzsperren sofort an eine Adresse deiner Wahl. So kann zum Beispiel n8n bei jeder neuen Buchung das Hallenlicht planen, oder eure Vereinssoftware erfährt, wenn ein Mitglied beitritt.

Webhooks findest du unter Admin → Automatisierungen im Bereich Webhooks. Auf derselben Seite verwaltest du auch die API-Schlüssel des Vereins, siehe Automatisierungen.

Wer darf was?

Beide Rechte vergibst du unter Admin → Rollen und Gruppen. Die Rolle Administrator hat sie automatisch. Wer Webhooks verwaltet, kann nur Ereignisse abonnieren, die er selbst sehen darf: Für Buchungsereignisse braucht es Belegung sehen, für Mitgliederereignisse Mitspieler suchen, für Platzsperren Plätze sehen.

Endpunkt anlegen

Ein Verein kann bis zu 10 Endpunkte anlegen.

Welche Ereignisse gibt es?

Ein Ereignis enthält nur IDs und Zeiten, keine Namen oder Kontaktdaten. Wer mehr braucht, holt es über die REST-API. Ereignisse aus der Zeit, bevor es den Endpunkt gab, werden nicht nachgeliefert.

So prüft dein Empfänger die Signatur

Jede Anfrage ist ein POST mit JSON-Body, zum Beispiel:

{
  "id": "evt_…",
  "type": "booking.created",
  "created_at": "2026-05-04T08:15:00.000Z",
  "tenant_id": "…",
  "object": { "type": "booking", "id": "…" },
  "data": { "booking_id": "…", "court_id": 3, "date": "2026-05-04", … }
}

Dazu kommt der Header CheckCourt-Signature: t=…,v1=…:

• t ist der Zeitpunkt in Unix-Sekunden.
• v1 ist ein HMAC-SHA256 (hex) über <t>.<Body>.
• Schlüssel ist das komplette Geheimnis einschließlich whsec_.
• Verwirf Anfragen, deren Zeitpunkt mehr als fünf Minuten abweicht.

Prüfung in Node.js:

import crypto from "node:crypto";

// rawBody: der unveränderte Body als String, nicht neu serialisiert
function isFromCheckCourt(secret, rawBody, header) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  const given = String(parts.v1 ?? "");
  return (
    given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(given), Buffer.from(expected))
  );
}

Antworte innerhalb von 10 Sekunden mit einem 2xx-Status. Sonst versucht CheckCourt es noch zweimal: nach 5 Minuten und nach einer weiteren Stunde. Dasselbe Ereignis kann dabei mehrfach ankommen: CheckCourt-Event-Id ist pro Ereignis eindeutig, damit erkennt dein Empfänger Doppelte.

Ein Beispiel in Python, alle Felder und Header, die Wartezeiten zwischen den Versuchen und Tipps gegen doppelte Verarbeitung findest du in der Entwicklerdokumentation zu Webhooks.

Testen

Klicke beim Endpunkt in der Liste oder auf seiner Seite auf Test senden. CheckCourt schickt dann das Ereignis webhook.test nur an diesen Endpunkt. Es geht in der nächsten Minute raus und erscheint danach im Zustellprotokoll. Tests funktionieren nur bei aktiven Endpunkten.

Zustellprotokoll

Ein Klick auf einen Endpunkt öffnet seine Seite mit den Abonnierten Ereignissen und dem Zustellprotokoll. Dort siehst du jede Zustellung, neueste zuerst, mit Zeitpunkt, Ereignis, Status, Zahl der Versuche, HTTP-Status und dem nächsten geplanten Versuch. Mit Mehr laden siehst du ältere Einträge. Über Alle Webhooks kehrst du zurück.

Über Details anzeigen siehst du Ereignis-ID, HTTP-Status, die Antwort des Empfängers und die Fehlermeldung. Mit Erneut senden schickst du eine Zustellung noch einmal, sie geht in der nächsten Minute raus. Einträge werden nach 30 Tagen gelöscht.

Endpunkt bearbeiten, deaktivieren, löschen

• Bearbeiten: URL, Beschreibung und Ereignisse ändern. Mit dem Schalter Aktiv deaktivierst du den Endpunkt vorübergehend. Abonnierte Ereignisse, die du mit deinen eigenen Rechten nicht sehen darfst, kannst du nicht ändern. Offene Zustellungen werden dabei abgebrochen, und während er aus ist, sammelt CheckCourt keine Ereignisse für ihn.
• Geheimnis neu erzeugen (Menü Weitere Aktionen mit den drei Punkten): Das bisherige Geheimnis gilt sofort nicht mehr. Bis du das neue beim Empfänger hinterlegst, schlägt dort die Signaturprüfung fehl.
• Löschen (ebenfalls unter Weitere Aktionen): Der Endpunkt bekommt keine Ereignisse mehr, und sein Zustellprotokoll wird gelöscht. Das lässt sich nicht rückgängig machen.

Alle Änderungen stehen im Aktivitätsprotokoll.

Automatisch deaktiviert

Schlagen die Zustellungen an einen Endpunkt fünf Tage lang fehl und ist der letzte Fehlschlag nicht älter als einen Tag, deaktiviert CheckCourt ihn automatisch. Der Endpunkt zeigt dann Automatisch deaktiviert, und wer ihn angelegt hat, bekommt eine E-Mail. Hat die Person das Recht Webhooks verwalten nicht mehr, geht die E-Mail an alle, die es haben.

Schon vorher warnt der Endpunkt mit „Zustellungen schlagen seit … fehl“. Prüfe dann im Zustellprotokoll die Fehlermeldung, behebe das Problem beim Empfänger und schalte den Endpunkt unter Bearbeiten → Aktiv wieder ein. Beim Einschalten beginnt die Zählung der Fehlschläge von vorn.

Webhooks und Apps

Webhooks hier sind für eure eigenen Anbindungen. Apps bekommen ihre Ereignisse unabhängig davon über ihre Installation und brauchen keinen Endpunkt.