Webhooks

Met webhooks laten je systemen reageren op wijzigingen in Elido zonder te pollen. Twee soorten endpoints:

• Gebeurtenis-endpoints - abonneer je op specifieke gebeurtenistypen (link.created, member.invited, enz.)
• SIEM-endpoints - firehose: elke gebeurtenis in de workspace, plus de volledige auditlogstroom als audit.event-payloads

Een endpoint aanmaken

Via Instellingen → Webhooks, of via de API:

curl -X POST https://api.elido.app/v1/webhooks/workspaces/1/webhooks \
  -H "Authorization: Bearer $ELIDO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/elido",
    "events": ["link.created", "link.deleted"],
    "kind": "event"
  }'

Het antwoord bevat een eenmalig secret:

{
  "endpoint": { "id": 7, "url": "...", "events": [...] },
  "secret": "whsec_a1b2c3d4..."
}

Sla het secret nu op - het wordt nooit meer teruggegeven. Gebruik het om handtekeningen van binnenkomende leveringen te verifiëren.

Handtekeningen verifiëren

Elke levering bevat:

X-Elido-Signature: v1=4f8a...
X-Webhook-Signature: v1=4f8a...   # backward-compatible alias
X-Webhook-Timestamp: 1735689600
X-Webhook-Event: link.created
X-Webhook-Delivery: 12345

Bereken HMAC-SHA256(secret, "{timestamp}.{raw_body}") en vergelijk met de waarde na v1= in constante tijd. Weiger leveringen ouder dan 5 minuten (now - timestamp > 300).

import { createHmac, timingSafeEqual } from "node:crypto";
 
function verify(secret: string, headers: Headers, rawBody: string) {
  const sig = headers.get("X-Webhook-Signature")?.replace(/^v1=/, "");
  const ts = headers.get("X-Webhook-Timestamp");
  if (!sig || !ts) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
 
  const expected = createHmac("sha256", secret)
    .update(`${ts}.${rawBody}`)
    .digest("hex");
 
  return timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

Nieuwe pogingen

Mislukte leveringen (alles wat geen 2xx is) worden herhaald met exponentiële backoff: 1 minuut, 5 minuten, 15 minuten. Na 3 pogingen wordt de levering als failed gemarkeerd.

Je kunt een mislukte (of al geleverde) poging handmatig opnieuw activeren via Webhooks → endpoint → Retry, of via:

curl -X POST \
  https://api.elido.app/v1/webhooks/workspaces/1/webhooks/7/deliveries/12345/retry \
  -H "Authorization: Bearer $ELIDO_TOKEN"

SIEM-modus

Een endpoint van het type SIEM ontvangt elke gebeurtenis in de workspace, ongeacht het abonnementsfilter per gebeurtenis. Dat omvat zowel operationele gebeurtenissen (link.created, member.invited, …) als de audit-log-firehose (audit.event).

Elke auditrelevante actie (BAA ondertekend, ledenrol gewijzigd, API-sleutel ingetrokken, …) verstuurt een audit.event-envelop:

{
  "type": "audit.event",
  "workspace_id": 1,
  "data": {
    "kind": "member.role_changed",
    "target_type": "member",
    "target_id": 42,
    "actor_user_id": 7,
    "ip": "1.2.3.4",
    "user_agent": "...",
    "metadata": { "from": "viewer", "to": "admin" },
    "recorded_at": "2026-05-01T12:00:00Z"
  },
  "timestamp": "2026-05-01T12:00:00Z"
}

Je SIEM-ingester (Splunk HEC, Datadog Logs, eigen relay) is verantwoordelijk voor het vertalen naar het eigen formaat.

Beschikbare gebeurtenistypen

Ook verstuurd (zie de webhookgids in het helpcentrum  voor payloads): link.expired, link.cap_reached, link.broken, member.role_changed, domain.verified, domain.ssl_failed, invitation.created, invitation.accepted, subscription.* and usage.threshold_80 / usage.threshold_100.

Gepland, vandaag niet verstuurd: gebeurtenissen per klik, link.clicked.aggregated, conversion.recorded, threshold.exceeded, domain.tls_renewed en qr.generated. Gebruik de analytics-API of het dashboard om klikactiviteit te volgen.