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#
- Organisation öffnen → Verwalten → Schnittstellen → Neuer Webhook. Höchstens 10 Webhooks je Organisation.
- 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. - Ereignisse wählen (siehe unten) und das Signaturgeheimnis einmalig kopieren.
- Testen sendet ein Ereignis
ping.
Ereignisse#
| Ereignis | Wann |
|---|---|
event.created | Termin angelegt |
event.updated | Termin geändert |
event.cancelled | Termin abgesagt |
member.joined | Mitglied beigetreten |
member.left | Mitglied ausgetreten |
post.created | Beitrag veröffentlicht |
announcement.created | Mitteilung veröffentlicht |
task.created | Aufgabe angelegt |
presse.veroeffentlicht | Pressemeldung oder News veröffentlicht (nur Plattform-Organisation) |
ping | Testereignis, 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…" }
}| Kopf | Bedeutung |
|---|---|
X-Clup-Event | Art des Ereignisses, z. B. event.created |
X-Clup-Delivery | Kennung der Zustellung; zum Entdoppeln |
X-Clup-Signature | t=<Sekunden>,v1=<hex> |
Content-Type | application/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 entsprechenWiederholungen und Abschaltung#
| Versuch | Wartezeit nach dem Fehlschlag |
|---|---|
| Erste Zustellung | sofort |
| Wiederholung 1 | 1 Min. |
| Wiederholung 2 | 5 Min. |
| Wiederholung 3 | 30 Min. |
| Wiederholung 4 | 2 Std. |
| Wiederholung 5 | 6 Std. |
| Danach | Webhook 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.