Zum Inhalt springen
CLUP.life

Entwickler Webhooks

Webhooks: Ereignisse, Signatur, Wiederholungen

CLUP.life-Webhooks: Ereignisse, dünne Nutzlast, Signaturprüfung (HMAC-SHA256), Wiederholungen und Beispiel-Empfänger in Node.js und Python.

Ein Webhook meldet deiner Adresse, dass etwas passiert ist — nicht was genau. Die Nutzlast ist absichtlich dünn: Art und Kennung. Die Einzelheiten holst du mit deinem Schlüssel ab und unterliegst damit den Rechten der Person. So fließen keine personenbezogenen Daten ungeprüft an Dritte.

Einrichten#

  1. Organisation öffnen → Verwalten → Schnittstellen → Neuer Webhook. Höchstens 10 Webhooks je Organisation.
  2. Adresse eintragen: nur https, Port 443, ohne Zugangsdaten und ohne IP-Adresse (nur Rechnernamen). Adresse und Geheimnis werden verschlüsselt gespeichert; die Oberfläche zeigt später nur den Rechnernamen.
  3. Ereignisse wählen (siehe unten) und das Signaturgeheimnis einmalig kopieren.
  4. Testen sendet ein Ereignis ping.

Ereignisse#

EreignisWann
event.createdTermin angelegt
foerderprogramm.createdFörderangebot der Organisation eingestellt
foerderprogramm.updatedFörderangebot der Organisation geändert
foerderprogramm.deletedFörderangebot der Organisation entfernt
event.updatedTermin geändert
event.cancelledTermin abgesagt
member.joinedMitglied beigetreten
member.leftMitglied ausgetreten
post.createdBeitrag veröffentlicht
post.updatedBeitrag geändert
post.deletedBeitrag gelöscht
announcement.createdMitteilung veröffentlicht
announcement.deletedMitteilung gelöscht
task.createdAufgabe angelegt
task.updatedAufgabe geändert
task.completedAufgabe erledigt
task.deletedAufgabe gelöscht
tasklist.createdAufgabenliste angelegt
decision.createdBeschluss ins Register eingetragen (nur für Mitglieder freigegebene)
decision.updatedBeschluss geändert, aufgehoben oder ersetzt (nur für Mitglieder freigegebene)
presse.veroeffentlichtPressemeldung oder News veröffentlicht (nur Plattform-Organisation)
pingTestereignis, ausgelöst mit „Testen“

Nutzlast und Köpfe#

{
  "id": "0198…",
  "type": "event.created",
  "createdAt": "2026-10-30T08:15:00.000Z",
  "organizationId": "0198…",
  "data": { "entityType": "event", "entityId": "0198…" }
}
KopfBedeutung
X-Clup-EventArt des Ereignisses, z. B. event.created
X-Clup-DeliveryKennung der Zustellung; zum Entdoppeln
X-Clup-Signaturet=<Sekunden>,v1=<hex>
Content-Typeapplication/json

Signatur prüfen#

Jede Zustellung trägt X-Clup-Signature: t=<Sekunden>,v1=<hex>. Berechne HMAC-SHA256(geheimnis, "<t>.<roher Körper>") über den unveränderten Rohkörper (vor dem Parsen!), vergleiche in konstanter Zeit und verwirf Ereignisse, deren t älter als 5 Minuten ist (Schutz gegen Wiedereinspielung).

Beispiel-Empfänger#

# Signatur von Hand prüfen (zum Testen). rohkoerper.json enthält den Körper byte-genau.
T=1767225600
printf '%s.%s' "$T" "$(cat rohkoerper.json)" | openssl dgst -sha256 -hmac "$CLUP_WEBHOOK_SECRET"
# die ausgegebene Hex-Zeichenkette muss dem Teil v1=… des Kopfes entsprechen

Wiederholungen und Abschaltung#

VersuchWartezeit nach dem Fehlschlag
Erste Zustellungsofort
Wiederholung 11 Min.
Wiederholung 25 Min.
Wiederholung 330 Min.
Wiederholung 42 Std.
Wiederholung 56 Std.
DanachWebhook wird abgeschaltet (5 gescheiterte Auslieferungen)
  • Antworte mit einem 2xx innerhalb von 8 Sekunden; alles andere (und Zeitüberschreitung) zählt als Fehlschlag. Die Antwort wird nur bis 64 KB gelesen.
  • Die Zustellung erfolgt mindestens einmal: Duplikate sind möglich. Entdopple mit X-Clup-Delivery.
  • Reihenfolge ist nicht garantiert; ein Ereignis kann nach einem späteren eintreffen.
  • Nach 5 gescheiterten Auslieferungen schaltet sich der Webhook selbst ab (in der Liste sichtbar). Nach der Fehlerbehebung wieder einschalten.
  • Die Auslieferungsliste enthält keine Inhalte und wird nach 14 Tagen gelöscht.
  • Sicherheit: Der Rechnername wird bei jeder Zustellung neu aufgelöst und gegen private/interne Adressbereiche geprüft (Schutz vor SSRF); Verbindungen werden nicht wiederverwendet.
Webhooks: Ereignisse, Signatur, Wiederholungen · CLUP.life