Sviluppatori 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 documentazione tecnica è disponibile in tedesco e inglese; nella tua lingua mostriamo la versione inglese.
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#
| Evento | Quando |
|---|---|
event.created | Evento creato |
event.updated | Evento modificato |
event.cancelled | Evento annullato |
member.joined | Membro iscritto |
member.left | Membro uscito |
post.created | Post pubblicato |
announcement.created | Comunicazione pubblicata |
task.created | Attività creata |
presse.veroeffentlicht | Comunicato stampa o notizia pubblicati (solo organizzazione della piattaforma) |
ping | Evento di prova, avviato con «Prova» |
Payload and headers#
{
"id": "0198…",
"type": "event.created",
"createdAt": "2026-10-30T08:15:00.000Z",
"organizationId": "0198…",
"data": { "entityType": "event", "entityId": "0198…" }
}| Intestazione | Significato |
|---|---|
X-Clup-Event | Tipo dell’evento, ad es. event.created |
X-Clup-Delivery | Identificativo della consegna; per eliminare i duplicati |
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#
| Tentativo | Attesa dopo il fallimento |
|---|---|
| Prima consegna | subito |
| Tentativo 1 | 1 min |
| Tentativo 2 | 5 min |
| Tentativo 3 | 30 min |
| Tentativo 4 | 2 h |
| Tentativo 5 | 6 h |
| Poi | Il webhook viene disattivato (5 consegne non riuscite) |
- 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.