Webhooks: abonneren op link- en klikgebeurtenissen

Webhooks sturen gebeurtenissen van Elido naar je server op het moment dat ze plaatsvinden. Gebruik ze in plaats van het pollen van de API wanneer je real-time gegevens nodig hebt — typische toepassingen zijn het synchroniseren van linkmetadata met je CRM, het bouwen van een aangepast dashboard, of het starten van een CI-pipeline wanneer een link wordt gepubliceerd.

Een webhook-eindpunt toevoegen

1. Dashboard → Webhooks → Nieuw eindpunt.
2. Plak de URL waarnaar we moeten POST'en. Deze moet HTTPS zijn — we weigeren gewone HTTP bij het aanmaken.
3. Kies de gebeurtenistypen die je wilt. De volledige lijst staat hieronder.
4. (Optioneel) Plak een ondertekeningsgeheim, of laat ons er een genereren. Het geheim wordt eenmalig getoond; kopieer het voordat je de pagina verlaat.
5. Opslaan. We sturen direct een testgebeurtenis zodat je kunt bevestigen dat het eindpunt bereikbaar is.

Gebeurteniscatalogus

De huidige gebeurtenistypen. Namen volgen <resource>.<actie> en blijven stabiel over versies heen.

• link.created — een nieuwe korte link is aangemaakt.
• link.updated — bestemming, slug, vervaltermijn of wachtwoord is gewijzigd.
• link.deleted — link is zacht verwijderd (nog 30 dagen te herstellen).
• link.clicked.aggregated — elke 60 seconden versturen we de klikaantallen per link voor het voorgaande venster. We leveren geen gebeurtenissen per individuele klik via webhooks (het volume zou de meeste eindpunten overbelasten) — gebruik de klikexport voor ruwe gebeurtenisgegevens.
• domain.verified — de DNS-controle van een aangepast domein is geslaagd.
• domain.tls_renewed — Caddy heeft het TLS-certificaat voor een aangepast domein vernieuwd.
• qr.generated — een QR-code SVG/PNG is gegenereerd.
• abuse.flagged — onze URL-scanner heeft een bestemming als verdacht gemarkeerd.
• member.invited / member.removed — wijzigingen in workspace-lidmaatschap.

Vorm van de payload

Elke gebeurtenis heeft dezelfde envelop:

{
  "id": "evt_2c8L9N4M5",
  "type": "link.created",
  "created_at": "2026-05-15T09:42:11.382Z",
  "workspace_id": 4123,
  "data": {
    "link_id": 891234,
    "slug": "spring-2026",
    "destination": "https://acme.com/spring-sale",
    "created_by": "user_5821"
  }
}

id is uniek per levering. Gebruik dit voor idempotentie — als je hetzelfde id twee keer ontvangt (omdat we opnieuw hebben geprobeerd), sla het duplicaat dan over.

Handtekeningen verifiëren

We ondertekenen elke webhook-body met HMAC-SHA256 met het geheim van je eindpunt. De handtekening staat in de header Elido-Signature als t=<unix_ts>,v1=<hex>.

Verifiëren in Node:

import { createHmac } from "node:crypto";

function verify(secret: string, body: string, header: string): boolean {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${body}`)
    .digest("hex");
  return expected === parts.v1;
}

Herhaalpogingen

We proberen mislukte leveringen (elke niet-2xx-respons, of geen respons binnen 10 seconden) opnieuw met exponentiële backoff: 30s, 1m, 5m, 30m, 2u, 12u. Na 6 mislukkingen markeren we het eindpunt als failing en stoppen we met opnieuw proberen voor die specifieke gebeurtenis. Het eindpunt blijft geabonneerd; nieuwe gebeurtenissen blijven een leveringspoging doen.

Blijft het eindpunt failing gedurende 5 opeenvolgende leveringen → we schakelen het automatisch uit en mailen de workspace-eigenaar. Schakel het weer in via het dashboard zodra je je server hebt gerepareerd.

Bezorglogboek

Open elke webhook in het dashboard om de laatste 500 leveringen te zien, met statuscode, responstijd en de request-/response-body voor elk. Mislukte leveringen kunnen vanuit deze weergave handmatig opnieuw worden afgespeeld.

Lokaal testen

Gebruik de Elido CLI om webhooks door te sturen naar localhost:

npx @elido/cli webhooks forward --url http://localhost:3000/webhooks

De CLI registreert een tijdelijk eindpunt dat blijft bestaan tot je Ctrl-C drukt, tunnelt leveringen naar je machine en drukt de request-body af voor elke gebeurtenis.

Limieten

• 20 eindpunten per workspace (Pro), 100 (Business).
• Maximaal 10 KB voor de ondertekende payload. Grotere payloads worden gesplitst — data bevat een vlag truncated: true en een URL om de volledige body op te halen.
• 50 gebeurtenissen per seconde volgehouden per eindpunt. Pieken worden in de wachtrij gezet.

Probleemoplossing

Eindpunt geeft 401 aan in het bezorglogboek. Je eindpunt verifieert handtekeningen met het verkeerde geheim. Vergelijk het geheim in Webhooks → Eindpunt → Instellingen met het geheim dat je server heeft opgeslagen.

Sommige gebeurtenissen komen twee keer binnen. Ofwel hebben we opnieuw geprobeerd na een trage respons, ofwel is je eindpunt getimeout zonder te reageren. Gebruik het id van de gebeurtenis voor idempotentie.

De aantallen van link.clicked.aggregated komen niet overeen met het analytics-dashboard. Het dashboard is real-time (binnen 30s na de klik); de webhook wordt in vensters van 60s verwerkt. Er is ook een kleine (~1%) afwijking omdat bots die uit het dashboard worden gefilterd, nog wel zijn opgenomen in de ruwe aggregaten totdat het bot-filtervenster sluit.