11 Min. LesezeitFunktionen

Webhooks für Link-Events: Payloads, Signaturen, Retries

URL-Shortener-Webhooks für Link- und Klick-Events: der Payload-Envelope, click.created, X-Elido-Signature-Prüfung in Node und Python, Retries.

Marius Voß
DevRel · edge infra

Die URL-Shortener-Webhooks von Elido senden per POST einen signierten JSON-Envelope an Ihren HTTPS-Endpunkt, sobald sich in einem Workspace etwas ändert: Ein Link wird erstellt, bearbeitet, gelöscht, läuft ab oder erreicht sein Klicklimit, ein Mitglied wird eingeladen, eine Domain wird verifiziert. Jede Anfrage trägt einen Header X-Elido-Signature: v1=<hex>, das ist HMAC-SHA256 über {timestamp}.{raw_body}, und eine fehlgeschlagene Zustellung bekommt innerhalb von etwa zwanzig Minuten drei Versuche.

Klicks haben ein eigenes Event, click.created, mit eigenen Regeln: ein datenschutzreduzierter Payload, ein Ratenlimit pro Endpunkt und ein Opt-in für Bot-Traffic. Der letzte Abschnitt behandelt es. Dieser Beitrag ist die ausgehende Hälfte der API-Oberfläche; die Schnellstartanleitung zu URL-Shortener-API + SDKs deckt die eingehende Hälfte ab, und Smart Links erklärt ist der Feature-Cornerstone, aus dem die Link-Events stammen.

Jedes Event unten erreicht einen Webhook-Endpunkt, der es namentlich abonniert hat. Das Formular für neue Endpunkte im Dashboard bietet Checkboxen für die acht häufigsten; die API akzeptiert jeden Namen aus der Liste.

EventWird ausgelöst, wennDashboard-Checkbox
link.createdEin Link erstellt wird, einzeln oder per Bulk-Importja
link.updatedZiel, Einstellungen oder Status sich ändern, bei Bulk-Änderungen, Wiederherstellungenja
link.deletedEin Link gelöscht wird, einzeln oder per Bulkja
link.expiredEin Link sein Ablaufdatum überschreitetnur API
link.cap_reachedEin Link seine maximale Klickzahl erreichtnur API
link.brokenDie Prüfung auf defekte Links sieht, dass das Ziel ausfälltnur API
click.createdEin Klick wird gezählt (Bots und Scanner übersprungen, außer per Opt-in)ja, nie vorab angehakt
workspace.created, workspace.updatedEin Workspace bereitgestellt wird oder sich seine Einstellungen ändernja
member.invited, member.removedEin Mitglied hinzugefügt (direkt, per SCIM oder angenommener Einladung) oder entfernt wirdja
member.role_changedSich die Rolle eines Mitglieds ändertnur API
invitation.created, invitation.acceptedEine Einladung gesendet oder angenommen wirdnur API
domain.verified, domain.ssl_failedEine Custom Domain die DNS-Prüfungen besteht oder sie nach 24 Stunden noch nicht bestehtnur API
audit.eventBei jedem Eintrag im Audit-Logja

Verschlüsselte Links fügen zwei weitere hinzu, link.encrypted_created und link.encryption_rotated. Wollen Sie die Liste nicht von Hand aktuell halten, legen Sie einen siem-Endpunkt an: Er erhält jedes Event im Workspace, Audit-Einträge eingeschlossen, ganz ohne Abonnement-Filter. Die einzige Ausnahme ist click.created, das nur event-Endpunkte erreicht, bei denen es angehakt ist.

Abrechnungs-Events laufen durch dieselbe Queue. Der Billing-Service veröffentlicht subscription.created, subscription.activated, subscription.paused, subscription.resumed, subscription.frozen, subscription.unfrozen, subscription.change_scheduled, subscription.change_canceled, usage.threshold_80, usage.threshold_100 und usage.overage_charged. Auch ein siem-Endpunkt erhält sie.

Auf der Roadmap, noch nicht live: Filter pro Endpunkt wie "nur Links im Ordner X". Bis dahin filtern Sie in Ihrem Handler nach data.slug oder data.link_id.

Die Elido-Webhook-Endpunkt-Seite mit ihrem Zustellungsprotokoll, das zugestellte Ereignisse, eine wiederholte Zustellung und eine fehlgeschlagene mit Statuscode 503 zeigt

Einen Webhook-Endpunkt mit der API anlegen

Ein Endpunkt gehört zu einem Workspace. Sie legen ihn mit einem POST an /v1/workspaces/{workspace_id}/webhooks an:

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

Die Antwort ist 201 mit dem Endpunkt und, für die Arten event und siem, einem einmaligen Secret:

{
  "endpoint": {
    "id": 7,
    "workspace_id": 42,
    "url": "https://hooks.example.com/elido",
    "events": ["link.created", "link.updated", "link.deleted"],
    "is_active": true,
    "description": "CRM sync",
    "kind": "event",
    "config": {},
    "created_at": "2026-09-21T09:12:44Z"
  },
  "secret": "whsec_9f2c..."
}

Elido erzeugt das Secret; Sie senden keines mit. Kopieren Sie es jetzt, denn kein späterer Aufruf gibt es zurück. kind kennt sechs Werte. event und siem sind die signierten JSON-Zustellungen, um die es in diesem Beitrag geht. discord, telegram, slack und sentry formen dieselben Events in eine Chat-Nachricht oder ein Sentry-Event um, authentifizieren sich über die URL oder ein verschlüsseltes Bot-Token und tragen keine HMAC-Header.

Beim Anlegen kommt es auf den Tarif an. Ein event-Endpunkt braucht Pro, Business oder Enterprise, und ein Free-Workspace erhält 402 Payment Required (das Dashboard öffnet stattdessen den Upgrade-Dialog). Ein siem-Endpunkt braucht Business oder Enterprise. Chat- und Sentry-Kanäle haben keine Tarifbeschränkung. Bereits bestehende Endpunkte liefern weiter aus, wenn der Workspace später downgradet.

Berechtigungen: Endpunkte und das Zustellungsprotokoll zu lesen erfordert workspace.view. Anlegen, Bearbeiten, Löschen, ein Secret rotieren oder eine Zustellung erneut senden erfordert workspace.edit, also einen Admin oder Owner. Ein API-Key funktioniert innerhalb des Workspace, für den er ausgestellt wurde, und nie oberhalb der bei der Erstellung gewählten Rolle, ein Key auf Viewer-Ebene erhält beim obigen POST also ein 403. Vollständige Referenz: die Webhook-Dokumentation.

Der Webhook-Payload-Envelope

Jede signierte Zustellung hat denselben Envelope mit vier Feldern. data enthält den geänderten Datensatz, bei Link-Events also die Link-Zeile:

{
  "type": "link.created",
  "workspace_id": 42,
  "data": {
    "id": 91834,
    "workspace_id": 42,
    "domain_id": 3,
    "slug": "spring-sale",
    "destination_url": "https://shop.example.com/spring",
    "title": "Spring sale landing",
    "tags": ["newsletter"],
    "status": "active",
    "expires_at": null,
    "max_clicks": null,
    "redirect_status": 302,
    "created_by_user_id": 17,
    "created_at": "2026-09-21T09:14:02.184311Z"
  },
  "timestamp": "2026-09-21T09:14:02Z"
}

Dieses Beispiel ist gekürzt; das echte data trägt jede Spalte des Links, einschließlich Targeting-Regeln, Ordner, Kampagne und Scan-Feldern. Im Body gibt es weder eine Event-ID noch eine short_url, bauen Sie die Kurz-URL bei Bedarf also aus Ihrer Domain und dem slug. Geplante Events senden stattdessen ein kleineres Objekt: link.expired hat link_id, slug und destination_url, und link.cap_reached ergänzt cap und clicks.

Eine Korrektur, die Sie kennen sollten, falls Sie Payloads vor dem Redaktions-Fix geloggt haben: Secret-Felder werden jetzt entfernt, bevor ein Payload Elido verlässt. Der password_hash eines passwortgeschützten Links und das token einer Einladung erschienen früher in data; das ist nicht mehr der Fall, weder in neuen Zustellungen noch im Zustellungsprotokoll. Haben Sie alte Payloads gespeichert, sollten Sie diese Daten löschen.

Den Header X-Elido-Signature prüfen

Jede signierte Anfrage trägt diese Header:

X-Elido-Signature: v1=5d8f0c3e...
X-Webhook-Signature: v1=5d8f0c3e...
X-Webhook-Timestamp: 1790068442
X-Webhook-Event: link.created
X-Webhook-Delivery: 55120
User-Agent: Elido-Webhooks/1.0

Die beiden Signatur-Header enthalten denselben Wert, und X-Webhook-Signature ist der abwärtskompatible Alias. Elido berechnet HMAC-SHA256 nach RFC 2104, mit dem gesamten String whsec_... als Schlüssel, über den Zeitstempel, einen Punkt und die rohen Body-Bytes. Dem Hex-Digest wird v1= vorangestellt. Im Header gibt es kein Feld t=; der Zeitstempel steht in einem eigenen Header.

Ablauf der Signaturprüfung: Die Header X-Elido-Signature und X-Webhook-Timestamp sowie der rohe Body und das Secret speisen ein HMAC-SHA256 über ts, Punkt, Body, in konstanter Zeit als v1=-Hex verglichen.

Signieren Sie in Node die rohen Bytes, nicht ein neu serialisiertes Objekt. Express braucht dafür auf dieser Route express.raw({ type: "application/json" }):

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyElido(secret, headers, rawBody, toleranceSec = 300) {
  const ts = headers["x-webhook-timestamp"] ?? "";
  if (!/^\d+$/.test(ts)) return false;
  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;

  const mac = createHmac("sha256", secret).update(`${ts}.`).update(rawBody);
  const expected = Buffer.from("v1=" + mac.digest("hex"));

  // During a rotation the old secret signs X-Elido-Signature-Previous.
  return ["x-elido-signature", "x-elido-signature-previous"].some((name) => {
    const got = Buffer.from(headers[name] ?? "");
    return got.length === expected.length && timingSafeEqual(got, expected);
  });
}

Die Längenprüfung ist wichtig: timingSafeEqual in Node wirft bei Buffern unterschiedlicher Größe einen Fehler, statt false zurückzugeben. Die Python-Version mit dem Standard-hmac-Modul:

import hashlib
import hmac
import time


def verify_elido(secret: str, headers, raw_body: bytes, tolerance: int = 300) -> bool:
    ts = headers.get("X-Webhook-Timestamp", "")
    if not ts.isdigit() or abs(time.time() - int(ts)) > tolerance:
        return False
    digest = hmac.new(secret.encode(), ts.encode() + b"." + raw_body, hashlib.sha256)
    expected = "v1=" + digest.hexdigest()
    for name in ("X-Elido-Signature", "X-Elido-Signature-Previous"):
        got = headers.get(name)
        if got and hmac.compare_digest(got, expected):
            return True
    return False

Schlägt die Prüfung dauerhaft fehl, bietet der Leitfaden zur Webhook-Signaturprüfung eine Go-Version, einen n8n-Code-Node und die üblichen Ursachen für eine Abweichung. Das Fünf-Minuten-Fenster ist Ihre Prüfung, nicht unsere. Elido stempelt bei jedem Versuch, Retries eingeschlossen, einen frischen Zeitstempel, sodass ein legitimer Retry nie veraltet aussieht. Ohne das Fenster könnte jeder, der eine Anfrage mitgeschnitten hat, sie nächste Woche erneut abspielen (Replay), und die Signatur würde immer noch passen.

Die Rotation läuft über POST /v1/workspaces/{workspace_id}/webhooks/{id}/rotate-secret oder den Button Rotate auf der Endpunktseite. Das neue Secret erhalten Sie einmal. Die nächsten sieben Tage trägt jede Zustellung zusätzlich X-Elido-Signature-Previous, signiert mit dem alten Secret, weshalb beide Funktionen oben es versuchen. Rollen Sie das neue Secret irgendwann in dieser Woche aus, und nichts schlägt fehl.

Die Webhook-Retry-Policy

Der Delivery-Worker holt ausstehende Zustellungen alle paar Sekunden ab, eine Link-Änderung erreicht Sie also meist innerhalb von Sekunden. Jede 2xx-Antwort markiert die Zustellung als erledigt. Ein Nicht-2xx-Status, ein Netzwerkfehler oder keine Antwort innerhalb von 10 Sekunden zählt als fehlgeschlagener Versuch.

Balkendiagramm des Webhook-Retry-Plans: Versuch 1 bei T+0, Versuch 2 fünf Minuten nach einem Fehlschlag bei T+5m, Versuch 3 fünfzehn Minuten später bei T+20m, danach wird die Zustellung als fehlgeschlagen markiert, ohne weitere automatische Versuche.

Drei Versuche pro Zustellung, zwanzig Minuten von Anfang bis Ende. Das ist mit Absicht kurz, und ehrlich gesagt kürzer, als ich es für einen Empfänger hinter einem wackligen VPN wählen würde. Ein zweistündiger Ausfall auf Ihrer Seite wird von den automatischen Retries nicht abgedeckt. Das übernimmt das Zustellungsprotokoll: GET /v1/workspaces/{workspace_id}/webhooks/{id}/deliveries listet jede Zustellung mit Status, HTTP-Code, Latenz, Anzahl der Versuche und Zeit des nächsten Retries, und die Endpunktseite zeigt dieselben Zeilen mit einem Retry-Button. Retry, oder POST .../deliveries/{delivery_id}/retry, setzt eine fehlgeschlagene oder zugestellte Zustellung mit einem frischen Budget von drei Versuchen zurück und liefert 202. Eine noch ausstehende Zustellung erhält 409.

Manche Fehler überspringen die Retries. Ein Telegram-Endpunkt ohne chat_id oder ein fehlerhafter Sentry-DSN wird sofort als fehlgeschlagen markiert, weil eine Wiederholung der Anfrage die Konfiguration nicht behebt. Um einen Endpunkt offline zu nehmen, ohne ihn zu löschen, senden Sie PUT mit "is_active": false; pausierte Endpunkte erhalten keine neuen Zustellungen.

Leistet Ihr Handler schwere Arbeit, geben Sie zuerst 200 zurück und stellen Sie den Job in eine Queue. An der Zehn-Sekunden-Grenze wird ein langsamer, aber erfolgreicher Handler zum Duplikat, womit wir bei der Deduplizierung wären.

Planen Sie einen Empfänger für Ihr Team? Die Feature-Seite zu Webhooks zeigt die Dashboard-Seite von alldem.

Webhook-Idempotenz und Reihenfolge

Elido liefert mindestens einmal (at least once). Der Abschnitt zu den Retries zeigte einen Weg, wie ein Duplikat entsteht: Ihr Handler committet die Arbeit, verpasst dann das Zehn-Sekunden-Fenster, und Elido sendet erneut. Ein manueller Retry sendet absichtlich neu.

Beide Fälle behalten denselben Wert von X-Webhook-Delivery, denn er ist die ID einer Zustellung an einen Endpunkt, nicht eines Versuchs. Verwenden Sie ihn als Schlüssel:

CREATE TABLE elido_webhook_seen (
  delivery_id BIGINT PRIMARY KEY,
  received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- in the handler, inside the same transaction as your work:
INSERT INTO elido_webhook_seen (delivery_id) VALUES ($1)
ON CONFLICT (delivery_id) DO NOTHING
RETURNING delivery_id;
-- no row back means you've already handled this delivery

Zwei Endpunkte, die dasselbe Event abonniert haben, erhalten zwei verschiedene Delivery-IDs, deduplizieren Sie also pro Endpunkt. Bei seltenen Neustarts auf unserer Seite kann ein Event als zwei getrennte Zustellungen in die Queue geraten; würde ein doppeltes Schreiben schaden, ergänzen Sie eine zweite Absicherung über type plus data.id plus data.updated_at.

Eine Reihenfolge wird nicht zugesagt. Zustellungen gehen nach dem ältesten Fälligkeitszeitpunkt zuerst raus, aber ein Retry eines frühen Events kann nach einem späteren eintreffen. Vergleichen Sie data.updated_at mit dem Gespeicherten, bevor Sie einen Link überschreiben, und verlassen Sie sich für die Reihenfolge nicht auf den timestamp des Envelopes: Er hat nur Sekundengenauigkeit.

Der click.created-Webhook

click.created sendet pro gezähltem Klick eine signierte Zustellung. Er liegt nicht auf dem Redirect-Pfad: Der Redirect veröffentlicht den Klick und macht weiter, wie der Beitrag zur Fire-and-forget-Klick-Ingestion erklärt, und das Event wird später aus dem gespeicherten Klick gebaut. Rechnen Sie mit einigen Sekunden zwischen Klick und POST, nicht mit Millisekunden.

Das data-Objekt sieht so aus:

{
  "type": "click.created",
  "workspace_id": 42,
  "timestamp": "2026-11-12T10:04:31Z",
  "data": {
    "id": "clk_3_99120",
    "link_id": 9183,
    "workspace_id": 42,
    "slug": "spring",
    "host": "go.acme.example",
    "short_url": "https://go.acme.example/spring",
    "timestamp": "2026-11-12T10:04:29Z",
    "country": "DE",
    "device": "mobile",
    "browser": "Safari",
    "referer_host": "news.ycombinator.com",
    "ip": "203.0.113.0",
    "is_bot": false,
    "is_scanner": false
  }
}

Einige Regeln bestimmen, was ankommt:

  • Datenschutz zuerst. Der Payload wird nach den Analytics-Datenschutzeinstellungen des Workspace gebaut. Die IP ist immer nur das gekürzte Netz (/24 bei IPv4, /48 bei IPv6) und fehlt im Modus ohne personenbezogene Daten ganz. Der Referrer wird auf seinen Host gekürzt; Pfade und Query-Strings verlassen das System nie.
  • Bots sind standardmäßig aus. Klicks mit is_bot oder is_scanner (ein Mail-Sicherheitsscanner, der den Link vorab abruft) werden übersprungen, außer Sie setzen am Endpunkt das Häkchen „Bot- und Scanner-Klicks einbeziehen“ oder senden config.include_bot_clicks: true über die API. Bekannte Crawler und Link-Vorschau-Bots zählen nie als Klicks und werden daher nie gesendet.
  • Ein Ratenlimit, keine Queue. Jeder Endpunkt erhält höchstens 50 Klick-Events pro Sekunde. Der Überschuss wird verworfen, nicht verzögert, sodass ein viraler Link Ihren Empfänger nicht überrollen kann; es bedeutet aber auch, dass der Webhook in Spitzenzeiten kein vollständiges Hauptbuch ist. Gleichen Sie mit der Analytics-API ab, wenn jeder Klick zählt.
  • Deduplizieren Sie über data.id. Die Zustellung erfolgt wie bei jedem anderen Event mindestens einmal. data.id bleibt gleich, wenn ein Klick doppelt verarbeitet wird, und X-Webhook-Delivery deckt Wiederholungen einer einzelnen Zustellung ab.
  • Gleiche Retries, gleiche Signatur. Drei Versuche (sofort, +5 Minuten, +15 Minuten) und die X-Elido-Signature-Prüfung weiter oben in diesem Beitrag.

Nur event-Endpunkte, bei denen click.created angehakt ist, erhalten es. Das Dashboard-Formular listet es, hakt es aber nie vorab an, und Discord-, Telegram-, Sentry- und siem-Endpunkte erhalten es nicht. Zapier (ein Catch Hook in Webhooks by Zapier), Make (ein Custom Webhook) und n8n (ein Webhook-Node) können es alle als Trigger entgegennehmen.

Zwei weitere Wege bleiben für Klickdaten sinnvoll. Event-Forwarder machen aus jedem Klick ein serverseitiges Event in einem Tool, das Sie ohnehin nutzen: Mixpanel-Link-Click-Events, Klaviyo-Klick-Events in Profilen oder Datadog-Redirect-Metriken für Ops-Dashboards. Und die Analytics-API, GET /v1/analytics/workspaces/{workspace_id}/clicks/recent plus der Export clicks.csv, ist die vollständige Aufzeichnung. Webhooks vs. Polling beim Klick-Tracking geht durch, welcher Weg passt.

Lesen Sie den Cornerstone: Smart Links erklärt.

Weitere Beiträge im Blog

Häufig gestellte Fragen

Sendet Elido einen Webhook für jeden Link-Klick?

Ja, über das Event click.created: eine signierte Zustellung pro gezähltem Klick, einige Sekunden nach dem Klick. Klicks von Bots und Sicherheitsscannern werden übersprungen, außer der Endpunkt hat sich dafür entschieden, und jeder Endpunkt ist auf 50 Klick-Events pro Sekunde begrenzt, der Überschuss wird verworfen statt in eine Queue gestellt. Für eine vollständige Aufzeichnung eines viralen Links lesen Sie zusätzlich die Analytics-API.

Wie prüfe ich die Signatur eines Elido-Webhooks?

Berechnen Sie HMAC-SHA256 über den Wert von X-Webhook-Timestamp, einen Punkt und den rohen Request-Body, mit Ihrem whsec_-Secret als Schlüssel. Kodieren Sie das Ergebnis hexadezimal, stellen Sie v1= voran und vergleichen Sie es in konstanter Zeit mit dem Header X-Elido-Signature. Weisen Sie Zeitstempel ab, die älter als fünf Minuten sind.

Wie oft wiederholt Elido einen fehlgeschlagenen Webhook?

Jede Zustellung erhält drei Versuche: einen sofort, einen fünf Minuten nach einem Fehlschlag und einen fünfzehn Minuten danach. Jeder Nicht-2xx-Status, Netzwerkfehler oder jede Antwort, die länger als zehn Sekunden dauert, zählt als Fehlschlag. Nach dem dritten wird die Zustellung als fehlgeschlagen markiert, bis Sie auf Retry drücken.

Was ist der Unterschied zwischen X-Elido-Signature und X-Webhook-Signature?

Nur der Name. Beide Header tragen dieselbe v1=-Signatur. X-Elido-Signature ist der primäre, und X-Webhook-Signature bleibt als abwärtskompatibler Alias erhalten, nutzen Sie in neuem Code also den ersten. Bei einer Secret-Rotation sendet Elido sieben Tage lang zusätzlich X-Elido-Signature-Previous, signiert mit dem alten Secret.

Wie verhindere ich, dass derselbe Webhook zweimal verarbeitet wird?

Speichern Sie den Wert des Headers X-Webhook-Delivery und überspringen Sie jede Anfrage, deren Wert Sie schon behandelt haben. Er identifiziert eine Zustellung an einen Endpunkt und bleibt über automatische Retries und manuelle erneute Sendungen hinweg gleich, ein Unique-Index darauf genügt also.

Wer kann Webhooks in einem Workspace anlegen oder löschen?

Workspace-Admins und Owner. Endpunkte aufzulisten und das Zustellungsprotokoll zu lesen erfordert Lesezugriff; Anlegen, Bearbeiten, Löschen, Secret rotieren oder eine Zustellung erneut senden erfordert die Berechtigung workspace.edit. API-Keys sind auf die Rolle begrenzt, die bei der Erstellung des Keys gewählt wurde.

Elido testen

URL einfügen, kurzer Link in Sekunden

Kein Konto nötig. Link bleibt 30 Tage aktiv. Konto erstellen, um ihn dauerhaft zu behalten.

Kostenloses Konto erforderlich. Der Free-Plan enthält insgesamt 25 Links. Du hast schon ein Konto? Anmelden

Elido testen

URL-Shortener mit EU-Hosting: eigene Domains, tiefe Analytik und eine offene API. Kostenloser Tarif - keine Kreditkarte nötig.

Tags
url shortener webhooks
link click webhook
webhook signature verification
webhook retry policy
webhook idempotency
webhook payload

Weiterlesen