انتقل إلى المحتوى
CLUP.life
محتويات الوثائق

المطوّرون Webhooks

Webhooks: events, signature, retries

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

الوثائق التقنية متوفرة بالألمانية والإنجليزية؛ نعرض النسخة الإنجليزية بلغتك.

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#

الحدثمتى
event.createdأُنشئت فعالية
event.updatedتم تغيير فعالية
event.cancelledأُلغيت فعالية
member.joinedانضم عضو
member.leftغادر عضو
post.createdنُشر منشور
announcement.createdنُشر إعلان
task.createdأُنشئت مهمة
presse.veroeffentlichtنُشر خبر صحفي أو خبر (منظمة المنصة فقط)
pingحدث اختباري يُطلَق بزر «اختبار»

Payload and headers#

{
  "id": "0198…",
  "type": "event.created",
  "createdAt": "2026-10-30T08:15:00.000Z",
  "organizationId": "0198…",
  "data": { "entityType": "event", "entityId": "0198…" }
}
الترويسةالمعنى
X-Clup-Eventنوع الحدث، مثل event.created
X-Clup-Deliveryمعرّف عملية التسليم؛ لإزالة التكرار
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#

المحاولةمدة الانتظار بعد الفشل
التسليم الأولفورًا
إعادة المحاولة 11 د
إعادة المحاولة 25 د
إعادة المحاولة 330 د
إعادة المحاولة 42 س
إعادة المحاولة 56 س
بعد ذلكيتم إيقاف الـWebhook (5 عمليات تسليم فاشلة)
  • 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