İçeriğe geç
CLUP.life
Belgelerin içeriği

Geliştiriciler Webhooks

Webhooks: events, signature, retries

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

Teknik belgeler Almanca ve İngilizce sunulur; dilinizde İngilizce sürümü gösteriyoruz.

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#

  1. Open the organization → Manage → Interfaces → New webhook. At most 10 webhooks per organization.
  2. 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.
  3. Choose events (see below) and copy the signing secret once.
  4. Test sends a ping event.

Events#

OlayNe zaman
event.createdEtkinlik oluşturuldu
event.updatedEtkinlik değişti
event.cancelledEtkinlik iptal edildi
member.joinedÜye katıldı
member.leftÜye ayrıldı
post.createdGönderi yayınlandı
announcement.createdDuyuru yayınlandı
task.createdGörev oluşturuldu
presse.veroeffentlichtBasın bülteni veya haber yayımlandı (yalnızca platform kuruluşu)
ping“Test” ile tetiklenen test olayı

Payload and headers#

{
  "id": "0198…",
  "type": "event.created",
  "createdAt": "2026-10-30T08:15:00.000Z",
  "organizationId": "0198…",
  "data": { "entityType": "event", "entityId": "0198…" }
}
BaşlıkAnlamı
X-Clup-EventOlayın türü, ör. event.created
X-Clup-DeliveryTeslimatın kimliği; yinelenenleri ayıklamak için
X-Clup-Signaturet=<Sekunden>,v1=<hex>
Content-Typeapplication/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#

DenemeBaşarısızlıktan sonra bekleme
İlk teslimathemen
1. yeniden deneme1 dk
2. yeniden deneme5 dk
3. yeniden deneme30 dk
4. yeniden deneme2 sa
5. yeniden deneme6 sa
SonrasındaWebhook kapatılır (5 başarısız teslimat)
  • 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.
Webhooks: events, signature, retries · CLUP.life