Programiści Webhooks

Webhooks: events, signature, retries

CLUP.life webhooks: events, thin payload, signature verification (HMAC-SHA256), retries and example receivers in Node.js and Python.

Dokumentacja techniczna jest dostępna po niemiecku i angielsku; w Twoim języku pokazujemy wersję angielską.

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: https only, 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 ping event.

Events#

Wydarzenie	Kiedy
`event.created`	Wydarzenie utworzone
`event.updated`	Wydarzenie zmienione
`event.cancelled`	Wydarzenie odwołane
`member.joined`	Członek dołączył
`member.left`	Członek odszedł
`post.created`	Wpis opublikowany
`announcement.created`	Ogłoszenie opublikowane
`task.created`	Zadanie utworzone
`presse.veroeffentlicht`	Informacja prasowa lub wiadomość opublikowana (tylko organizacja platformy)
`ping`	Zdarzenie testowe, wywoływane przyciskiem „Testuj”

Payload and headers#

{
  "id": "0198…",
  "type": "event.created",
  "createdAt": "2026-10-30T08:15:00.000Z",
  "organizationId": "0198…",
  "data": { "entityType": "event", "entityId": "0198…" }
}

Nagłówek	Znaczenie
`X-Clup-Event`	Typ zdarzenia, np. event.created
`X-Clup-Delivery`	Identyfikator dostarczenia; do usuwania duplikatów
`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 entsprechen

Retries and disabling#

Próba	Czas oczekiwania po niepowodzeniu
Pierwsze dostarczenie	natychmiast
Ponowna próba 1	1 min
Ponowna próba 2	5 min
Ponowna próba 3	30 min
Ponowna próba 4	2 godz.
Ponowna próba 5	6 godz.
Potem	Webhook zostaje wyłączony (5 nieudanych dostarczeń)

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.