Webhooks: Link- und Workspace-Ereignisse abonnieren

Webhooks übertragen Ereignisse von Elido, sobald sie eintreten, an Ihren Server, sodass Sie die API nicht abfragen müssen. Typische Anwendungsfälle sind die Synchronisierung von Link-Metadaten mit einem CRM, das Aktualisieren eines internen Link-Index oder das Starten eines Jobs, wenn ein Link veröffentlicht wird.

Webhooks decken Änderungen an Links, Domains, Mitgliedern und dem Workspace ab. Einzelne Klicks werden nicht übertragen. Für Klickdaten verwenden Sie den Klick-Export oder eine Ereignisintegration wie Mixpanel. Webhook-Ereignisse pro Klick sind geplant.

Webhook-Endpunkt hinzufügen

1. Gehen Sie zu Dashboard → Webhooks.
2. Geben Sie die URL ein, an die wir POST-Anfragen senden sollen, sowie optional eine Beschreibung.
3. Wählen Sie den Endpunkttyp: Events (Sie wählen die Ereignistypen aus) oder SIEM (firehose) (jedes Ereignis im Workspace).
4. Bei einem Events-Endpunkt markieren Sie die gewünschten Ereignistypen. Die link.*-Ereignisse sind standardmäßig markiert.
5. Klicken Sie auf Add endpoint. Das Signaturgeheimnis wird einmal direkt unter dem Formular angezeigt. Kopieren Sie es jetzt: Elido zeigt es nicht noch einmal an.

Die URL muss HTTPS verwenden. Reines http:// wird beim Speichern des Endpunkts abgelehnt, außer bei localhost und 127.0.0.1, die für die lokale Entwicklung weiterhin zulässig sind.

Sie können einen Endpunkt in der Liste pausieren und fortsetzen. Ein pausierter Endpunkt erhält keine neuen Zustellungen, und alles, was für ihn noch in der Warteschlange steht, wartet, bis Sie ihn fortsetzen.

Wer Webhooks verwalten kann

Jede Person im Workspace kann Endpunkte und das Lieferprotokoll ansehen. Zum Erstellen, Bearbeiten, Pausieren, Löschen, Rotieren des Geheimnisses und Wiederholen einer Zustellung ist die Berechtigung workspace.edit erforderlich, über die die integrierten Rollen Admin und Owner verfügen. Ein API-Schlüssel kann dieselben Webhook-Endpunkte der API aufrufen, wenn seine Rolle diese Berechtigung hat.

Endpunkttypen

• Events (event): erhält nur die Ereignistypen, die Sie abonniert haben. Signiert.
• SIEM (siem): erhält jedes für den Workspace veröffentlichte Ereignis, einschließlich audit.event für jeden Eintrag im Prüfprotokoll. Signiert. Für Protokoll-Pipelines und Sicherheitstools vorgesehen.
• Discord, Telegram und Sentry: Chat- und Benachrichtigungskanäle, die dasselbe Zustellungssystem verwenden, aber das jeweilige Nachrichtenformat des Anbieters senden. Sie authentifizieren sich über die Anbieter-URL oder das Anbieter-Token und enthalten daher keine Signatur-Header. Siehe Discord, Telegram und Sentry.

Alle folgenden Informationen zu Signaturen und Geheimnissen gelten nur für Events- und SIEM-Endpunkte.

Ereigniskatalog

Die Namen folgen dem Muster <resource>.<action>. Das Dashboard-Formular bietet die häufigsten an. Über die API können Sie einen Events-Endpunkt für jeden Typ in dieser Liste abonnieren, und ein SIEM-Endpunkt empfängt alle davon.

In der Auswahl im Dashboard:

• link.created: Ein Kurzlink wurde erstellt, einschließlich in großen Mengen erstellter Links.
• link.updated: Ein Link wurde geändert (Ziel, Titel, Tags, Ablaufdatum und so weiter), wiederhergestellt, sein Status geändert oder sein Sicherheitsstatus durch Moderation geändert.
• link.deleted: Ein Link wurde als gelöscht markiert.
• workspace.updated: Workspace-Einstellungen wurden geändert.
• workspace.created: Wird veröffentlicht, wenn ein Workspace erstellt wird. Da in einem Workspace vor seiner Erstellung kein Endpunkt existieren kann, erhalten Sie dieses Ereignis normalerweise nicht.
• member.invited: Jemand ist dem Workspace durch direktes Hinzufügen, Annahme einer Einladung oder SCIM-Bereitstellung beigetreten.
• member.removed: Ein Mitglied wurde manuell oder über SCIM entfernt.
• audit.event: Ein Ereignis pro Eintrag im Prüfprotokoll.

Über die API oder einen SIEM-Endpunkt verfügbar:

• link.expired: Ein Link hat sein Ablaufdatum überschritten.
• link.cap_reached: Ein Link hat sein Klicklimit erreicht. data enthält cap und clicks.
• link.broken: Elidos Link-Health-Check hat festgestellt, dass das Ziel fehlschlägt. data enthält status_code, error_message und first_seen_at.
• link.encrypted_created und link.encryption_rotated: Für verschlüsselte Links.
• domain.verified: Eine benutzerdefinierte Domain hat die DNS-Prüfung bestanden.
• domain.ssl_failed: Die DNS-Einträge einer benutzerdefinierten Domain wurden 24 Stunden nach ihrem Hinzufügen weiterhin nicht gefunden. Trotz des Namens geht es um die DNS-Verifizierung, nicht um die Zertifikatserneuerung.
• member.role_changed: Die Rolle eines Mitglieds wurde geändert. data enthält old_role, new_role und changed_by_user_id.
• invitation.created und invitation.accepted.
• Abrechnungsereignisse: subscription.* (zum Beispiel subscription.activated, subscription.renewed, subscription.canceled) und usage.threshold_80, usage.threshold_100.

Geplant und heute noch nicht gesendet: link.clicked.aggregated (Klickzahlen pro Link und Zeitfenster), Ereignisse pro Klick, conversion.recorded, domain.tls_renewed, qr.generated und ein separates abuse.flagged-Ereignis. Eine Moderationsentscheidung zu einem Link trifft derzeit als link.updated mit dem neuen abuse_status ein.

Aufbau der Nutzlast

Jede signierte Zustellung ist ein POST mit Content-Type: application/json, User-Agent: Elido-Webhooks/1.0 und diesem Umschlag:

{
  "type": "link.created",
  "workspace_id": 4123,
  "timestamp": "2026-09-22T09:42:11Z",
  "data": {
    "id": 891234,
    "workspace_id": 4123,
    "domain_id": 12,
    "slug": "spring-2026",
    "destination_url": "https://acme.com/spring-sale",
    "title": "Spring sale",
    "tags": ["email"],
    "status": "active",
    "expires_at": null,
    "created_by_user_id": 5821,
    "created_at": "2026-09-22T09:42:11Z"
  }
}

• type ist der Ereignistyp. Er steht auch im Header X-Webhook-Event.
• timestamp ist der Zeitpunkt des Ereignisses in UTC.
• data hängt vom Ereignis ab. Bei link.*-Ereignissen ist es das vollständige Link-Objekt (das obige Beispiel ist gekürzt). Bei anderen Ereignissen ist es ein kleines Objekt mit den im Katalog aufgeführten IDs und Feldern.
• Geheimnisse verlassen Elido nie: Felder wie der Passwort-Hash eines Links oder ein Einladungstoken werden vor der Zustellung aus data entfernt.

Im Body gibt es noch kein Ereignisfeld id; eine ID pro Ereignis ist geplant. Verwenden Sie für Idempotenz den unten beschriebenen Header X-Webhook-Delivery.

Header und Signaturen

Jede Zustellung an einen Events- oder SIEM-Endpunkt enthält:

Header	Wert
X-Elido-Signature	v1= gefolgt von der hexadezimalen HMAC-SHA256-Signatur
X-Webhook-Signature	Derselbe Wert wie X-Elido-Signature, für ältere Integrationen beibehalten
X-Webhook-Timestamp	Unix-Zeit in Sekunden, zu der diese Anfrage signiert wurde
X-Webhook-Event	Der Ereignistyp, zum Beispiel link.created
X-Webhook-Delivery	Die Zustell-ID. Sie bleibt bei Wiederholungen derselben Zustellung gleich
X-Elido-Signature-Previous	Nur während einer Geheimnisrotation: dieselbe mit dem alten Schlüssel erzeugte Signatur

Die Signatur wird wie folgt berechnet:

v1=hex( HMAC-SHA256( secret, "{X-Webhook-Timestamp}.{raw request body}" ) )

Der Schlüssel ist Ihre vollständige Geheimniszeichenfolge einschließlich des Präfixes whsec_, unverändert verwendet. Signieren Sie die empfangenen Rohbytes, nicht ein erneut serialisiertes JSON-Objekt, und vergleichen Sie in konstanter Zeit. Ein kurzes Node-Beispiel (Express):

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

const SECRET = process.env.ELIDO_WEBHOOK_SECRET; // full whsec_... value

function same(a, b = "") {
  const x = Buffer.from(a);
  const y = Buffer.from(b);
  return x.length === y.length && timingSafeEqual(x, y);
}

const app = express();
app.post(
  "/webhooks/elido",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const ts = req.get("X-Webhook-Timestamp") ?? "";
    if (!/^\d+$/.test(ts) || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
      return res.status(400).send("stale timestamp");
    }
    const expected =
      "v1=" +
      createHmac("sha256", SECRET)
        .update(`${ts}.`)
        .update(req.body)
        .digest("hex");
    const ok = [
      req.get("X-Elido-Signature"),
      req.get("X-Elido-Signature-Previous"),
    ].some((sig) => same(expected, sig));
    if (!ok) return res.status(401).send("bad signature");

    const event = JSON.parse(req.body.toString("utf8"));
    // queue event for processing, then answer quickly
    res.sendStatus(200);
  },
);

Python- und Go-Versionen, einen Testvektor und häufige Fehler finden Sie unter So verifizieren Sie Webhook-Signaturen.

Signaturgeheimnis rotieren

Öffnen Sie den Endpunkt unter Dashboard → Webhooks und klicken Sie auf Rotate secret. Das neue whsec_-Geheimnis wird einmal angezeigt, und Elido signiert ab diesem Zeitpunkt damit.

Der alte Schlüssel bleibt während einer 7-tägigen Kulanzfrist gültig. Während dieser Zeit enthält jede Zustellung zwei Signaturen: X-Elido-Signature mit dem neuen Schlüssel und X-Elido-Signature-Previous mit dem alten, sodass ein noch nicht umgestellter Empfänger weiterhin verifizieren kann. Akzeptieren Sie beide Header, während Sie das neue Geheimnis ausrollen.

Für vor dem 22. September 2026 erstellte Endpunkte gilt eine Ausnahme: Bei ihrer ersten Rotation wird kein X-Elido-Signature-Previous erzeugt, sodass das ursprüngliche Geheimnis sofort ungültig wird. Stellen Sie das neue Geheimnis direkt nach dieser ersten Rotation auf Ihrem Server bereit. Seitdem erstellte Endpunkte signieren ab der ersten Rotation mit beiden Signaturen. Ab der zweiten Rotation gilt die 7-tägige Überschneidung.

Wiederholungen

Eine Zustellung schlägt bei jeder Nicht-2xx-Antwort, einem Netzwerkfehler oder ausbleibender Antwort innerhalb von 10 Sekunden fehl. Jede Zustellung erhält insgesamt 3 Versuche:

1. Der erste Versuch, wenige Sekunden nach dem Ereignis.
2. Eine Wiederholung etwa 5 Minuten nach dem ersten Fehler.
3. Eine letzte Wiederholung etwa 15 Minuten nach dem zweiten Fehler.

Wenn der dritte Versuch fehlschlägt, wird die Zustellung als failed markiert und nicht automatisch erneut versucht. Der Endpunkt bleibt aktiv und neue Ereignisse werden weiterhin zugestellt. Ihr Endpunkt kann dieselbe Zustellung mehr als einmal sehen (zum Beispiel, wenn er eine Anfrage verarbeitet, aber erst nach dem 10-Sekunden-Timeout geantwortet hat). Führen Sie daher anhand von X-Webhook-Delivery eine Deduplizierung durch.

Lieferprotokoll

Öffnen Sie einen Endpunkt unter Dashboard → Webhooks, um seine letzten 100 Zustellungen zu sehen. Für jede erhalten Sie den Ereignistyp, den Status (ausstehend, zugestellt oder fehlgeschlagen), den von Ihrem Server zurückgegebenen HTTP-Status, die Antwortzeit, die von 3 verwendeten Versuche, den Zeitpunkt der Erstellung und des Abschlusses, den Zeitpunkt der nächsten Wiederholung bei ausstehenden Zustellungen, den letzten Fehler und die vollständig gesendete Nutzlast.

Jede zugestellte oder fehlgeschlagene Zustellung hat eine Retry-Schaltfläche. Sie stellt dieselbe Zustellung erneut in die Warteschlange (dieselbe X-Webhook-Delivery-ID, frisch signiert) und gibt ihr ein neues Budget von 3 Versuchen. Über die API blättert GET /v1/workspaces/{workspace_id}/webhooks/{id}/deliveries mit limit (bis zu 100) und offset durch ältere Zustellungen, und POST .../deliveries/{delivery_id}/retry führt dasselbe wie die Schaltfläche aus. Wenn Sie eine Zustellung nicht selbst wiederholen können, kann der Elido-Support sie für Sie wiederholen.

Das Aufzeichnen des Antwort-Bodys Ihres Servers im Protokoll ist geplant.

Lokal testen

Ein CLI-Befehl, der Webhooks an localhost weiterleitet (npx @elido/cli webhooks forward), ist geplant. Bis dahin machen Sie Ihren lokalen Server über einen Tunnel wie ngrok oder Cloudflare Tunnel erreichbar, fügen Sie die HTTPS-URL des Tunnels als Endpunkt hinzu und entfernen Sie sie anschließend.

Limits

• 10 Sekunden, damit Ihr Endpunkt antwortet.
• 3 Zustellversuche pro Ereignis sowie manuelle Wiederholungen.
• Die API des Lieferprotokolls gibt höchstens 100 Zustellungen pro Seite zurück.

Fehlerbehebung

Signatur stimmt nie überein. Die häufigsten Ursachen: Ihr Framework hat das JSON geparst und vor dem Hashing erneut serialisiert (Hash des Roh-Bodys), Sie haben das Präfix whsec_ vom Schlüssel entfernt oder Sie signieren mit dem timestamp des Bodys statt mit dem Header X-Webhook-Timestamp. Der Beitrag zur Signaturverifizierung enthält einen Testvektor, mit dem Sie Ihren Code prüfen können.

Signatur stimmt nach einer Rotation nicht mehr überein. Auf Ihrem Server befindet sich noch das alte Geheimnis. Stellen Sie das neue bereit. Bei einem vor dem 22. September 2026 erstellten Endpunkt gibt es bei der ersten Rotation kein X-Elido-Signature-Previous, auf das Sie zurückgreifen könnten.

Einige Ereignisse kommen doppelt an. Elido hat es erneut versucht, weil Ihr Endpunkt mit einem Fehler geantwortet hat oder länger als 10 Sekunden gebraucht hat. Führen Sie anhand von X-Webhook-Delivery eine Deduplizierung durch und antworten Sie mit 2xx, bevor Sie langsame Arbeiten ausführen.

Ein Ereignistyp kommt nie an. Prüfen Sie, ob der Endpunkt dafür abonniert und nicht pausiert ist und ob der Typ im obigen Katalog steht. Als geplant markierte Typen werden noch nicht gesendet.