Webhooks: Link- und Klickereignisse abonnieren

Webhooks pushen Ereignisse von Elido auf Ihren Server, sobald sie auftreten. Verwenden Sie sie anstelle von API-Polling, wenn Sie Echtzeit-Daten benötigen — typische Anwendungsfälle sind das Synchronisieren von Link-Metadaten mit Ihrem CRM, der Aufbau eines benutzerdefinierten Dashboards oder das Starten einer CI-Pipeline, wenn ein Link veröffentlicht wird.

Einen Webhook-Endpunkt hinzufügen#

Dashboard → Webhooks → Neuer Endpunkt.
Fügen Sie die URL ein, an die wir POSTen sollen. Sie muss HTTPS sein — wir lehnen einfaches HTTP beim Erstellen ab.
Wählen Sie die Ereignistypen, die Sie möchten. Die vollständige Liste ist unten.
(Optional) Fügen Sie ein Signatur-Secret ein oder lassen Sie uns eines generieren. Das Secret wird einmal angezeigt; kopieren Sie es, bevor Sie die Seite verlassen.
Speichern. Wir senden sofort ein Testereignis, damit Sie bestätigen können, dass der Endpunkt erreichbar ist.

Ereigniskatalog#

Die aktuellen Ereignistypen. Namen folgen <Ressource>.<Aktion> und bleiben über Versionen hinweg stabil.

link.created — ein neuer Kurzlink wurde erstellt.
link.updated — Destination, Slug, Ablauf oder Passwort wurde geändert.
link.deleted — Link wurde soft-gelöscht (noch 30 Tage wiederherstellbar).
link.clicked.aggregated — alle 60 Sekunden senden wir die Klickzahlen pro Link für das vorherige Fenster. Wir liefern keine Pro-Klick-Ereignisse über Webhooks (das Volumen würde die meisten Endpunkte überlasten) — verwenden Sie den Klick-Export für Rohereignisdaten.
domain.verified — die DNS-Prüfung einer benutzerdefinierten Domain ist bestanden.
domain.tls_renewed — Caddy hat das TLS-Zertifikat für eine benutzerdefinierte Domain erneuert.
qr.generated — ein QR-Code-SVG/PNG wurde gerendert.
abuse.flagged — unser URL-Scanner hat eine Destination als verdächtig markiert.
member.invited / member.removed — Workspace-Mitgliedschaftsänderungen.

Nutzlast-Form#

Jedes Ereignis hat denselben Umschlag:

{
  "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 ist pro Lieferung eindeutig. Verwenden Sie es für Idempotenz — wenn Sie dieselbe id zweimal erhalten (weil wir erneut versucht haben), überspringen Sie das Duplikat.

Signaturen verifizieren#

Wir signieren jeden Webhook-Body mit HMAC-SHA256 unter Verwendung des Secrets Ihres Endpunkts. Die Signatur befindet sich im Elido-Signature-Header als t=<unix_ts>,v1=<hex>.

Zur Verifizierung 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;
}

Wir schließen den Zeitstempel in die signierte Nutzlast ein, um Replays zu verhindern. Lehnen Sie Ereignisse ab, bei denen |jetzt - t| > 300 Sekunden ist.

Wiederholungsversuche#

Wir wiederholen fehlgeschlagene Lieferungen (jede Nicht-2xx-Antwort oder keine Antwort innerhalb von 10 Sekunden) mit exponentiellem Backoff: 30s, 1m, 5m, 30m, 2h, 12h. Nach 6 Fehlern markieren wir den Endpunkt als fehlschlagend und hören auf, dieses spezifische Ereignis zu wiederholen. Der Endpunkt bleibt abonniert; neue Ereignisse versuchen weiterhin die Lieferung.

Endpunkt bleibt für 5 aufeinanderfolgende Lieferungen fehlschlagend → wir deaktivieren ihn automatisch und senden eine E-Mail an den Workspace-Inhaber. Reaktivieren Sie ihn im Dashboard, sobald Sie Ihren Server behoben haben.

Lieferprotokoll#

Öffnen Sie einen Webhook im Dashboard, um die letzten 500 Lieferungen mit Statuscode, Antwortzeit und dem Anfrage-/Antwort-Body für jede zu sehen. Fehlgeschlagene Lieferungen können von dieser Ansicht aus manuell erneut abgespielt werden.

Lokales Testen#

Verwenden Sie die Elido-CLI, um Webhooks an localhost weiterzuleiten:

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

Die CLI registriert einen temporären Endpunkt, der bis zu Ihrem Ctrl-C aktiv bleibt, tunnelt Lieferungen zu Ihrem Rechner und druckt den Anfrage-Body für jedes Ereignis.

Limits#

20 Endpunkte pro Workspace (Pro), 100 (Business).
Maximale signierte Nutzlastgröße 10 KB. Größere Nutzlasten werden aufgeteilt — data enthält ein truncated: true-Flag und eine URL zum Abrufen des vollständigen Bodys.
50 Ereignisse pro Sekunde dauerhaft pro Endpunkt. Bursts werden in die Warteschlange gestellt.

Fehlerbehebung#

Endpunkt meldet 401 im Lieferprotokoll. Ihr Endpunkt verifiziert Signaturen mit dem falschen Secret. Vergleichen Sie das Secret in Webhooks → Endpunkt → Einstellungen mit dem, das Ihr Server gespeichert hat.

Einige Ereignisse kommen zweimal an. Entweder haben wir nach einer langsamen Antwort wiederholt, oder Ihr Endpunkt hat eine Zeitüberschreitung ohne Antwort. Verwenden Sie die Ereignis-id für Idempotenz.

link.clicked.aggregated-Anzahlen stimmen nicht mit dem Analytics-Dashboard überein. Das Dashboard ist Echtzeit (innerhalb von 30s nach einem Klick); der Webhook wird alle 60s gefenstert. Es gibt auch eine kleine (~1%) Diskrepanz, weil aus dem Dashboard herausgefilterte Bots noch in rohen Aggregaten enthalten sind, bis das Bot-Filter-Fenster sich schließt.