Desarrolladores 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 documentación técnica está disponible en alemán e inglés; en tu idioma mostramos la versión en inglés.
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 | Cuándo |
|---|---|
event.created | Evento creado |
event.updated | Evento modificado |
event.cancelled | Evento cancelado |
member.joined | Miembro incorporado |
member.left | Miembro dado de baja |
post.created | Publicación publicada |
announcement.created | Aviso publicado |
task.created | Tarea creada |
presse.veroeffentlicht | Comunicado de prensa o noticia publicados (solo organización de la plataforma) |
ping | Evento de prueba, activado con «Probar» |
Payload and headers#
{
"id": "0198…",
"type": "event.created",
"createdAt": "2026-10-30T08:15:00.000Z",
"organizationId": "0198…",
"data": { "entityType": "event", "entityId": "0198…" }
}| Cabecera | Significado |
|---|---|
X-Clup-Event | Tipo del evento, p. ej. event.created |
X-Clup-Delivery | Identificador de la entrega; para evitar duplicados |
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#
| Intento | Espera tras el fallo |
|---|---|
| Primera entrega | de inmediato |
| Reintento 1 | 1 min |
| Reintento 2 | 5 min |
| Reintento 3 | 30 min |
| Reintento 4 | 2 h |
| Reintento 5 | 6 h |
| Después | El webhook se desactiva (5 entregas fallidas) |
- 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.