Développeurs Webhooks
Webhooks: events, signature, retries
CLUP.life webhooks: events, thin payload, signature verification (HMAC-SHA256), retries and example receivers in Node.js and Python.
La documentation technique existe en allemand et en anglais ; dans votre langue, nous affichons la version anglaise.
A webhook tells your address that something happened — not what exactly. The payload is deliberately thin: type and identifier. You fetch the details with your key and are bound by the person’s rights. This way no personal data flows unchecked to third parties.
Setting up#
- Open the organization → Manage → Interfaces → New webhook. At most 10 webhooks per organization.
- Enter the address:
httpsonly, port 443, no credentials and no IP address (host names only). Address and secret are stored encrypted; the interface later shows only the host name. - Choose events (see below) and copy the signing secret once.
- Test sends a
pingevent.
Events#
| Événement | Quand |
|---|---|
event.created | Événement créé |
event.updated | Événement modifié |
event.cancelled | Événement annulé |
member.joined | Membre inscrit |
member.left | Membre parti |
post.created | Publication mise en ligne |
announcement.created | Annonce publiée |
task.created | Tâche créée |
presse.veroeffentlicht | Communiqué de presse ou actualité publié (uniquement organisation de la plateforme) |
ping | Événement de test, déclenché avec « Tester » |
Payload and headers#
{
"id": "0198…",
"type": "event.created",
"createdAt": "2026-10-30T08:15:00.000Z",
"organizationId": "0198…",
"data": { "entityType": "event", "entityId": "0198…" }
}| En-tête | Signification |
|---|---|
X-Clup-Event | Type de l’événement, p. ex. event.created |
X-Clup-Delivery | Identifiant de la livraison ; pour éviter les doublons |
X-Clup-Signature | t=<Sekunden>,v1=<hex> |
Content-Type | application/json |
Verifying the signature#
Every delivery carries X-Clup-Signature: t=<seconds>,v1=<hex>. Compute HMAC-SHA256(secret, "<t>.<raw body>") over the unmodified raw body (before parsing!), compare in constant time and discard events whose t is older than 5 minutes (replay protection).
Example receivers#
# 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 entsprechenRetries and disabling#
| Tentative | Attente après l’échec |
|---|---|
| Première livraison | immédiatement |
| Nouvelle tentative 1 | 1 min |
| Nouvelle tentative 2 | 5 min |
| Nouvelle tentative 3 | 30 min |
| Nouvelle tentative 4 | 2 h |
| Nouvelle tentative 5 | 6 h |
| Ensuite | Le webhook est désactivé (5 livraisons échouées) |
- Answer with a 2xx within 8 seconds; anything else (and a timeout) counts as a failure. The response is read only up to 64 KB.
- Delivery is at least once: duplicates are possible. De-duplicate with
X-Clup-Delivery. - Order is not guaranteed; an event may arrive after a later one.
- After 5 failed deliveries the webhook switches itself off (visible in the list). Re-enable it after fixing the problem.
- The delivery list contains no content and is deleted after 14 days.
- Security: the host name is re-resolved on every delivery and checked against private/internal ranges (SSRF protection); connections are not reused.