Webhooks. Echtzeit-Ereignisse, zuverlässig zugestellt.

Lesen Sie den rohen Anfrage-Body als Bytes (vor jeglichem JSON-Parsing), berechnen Sie HMAC-SHA256 über die rohen Bytes unter Verwendung des Shared Secret Ihres Endpunkts, kodieren Sie das Ergebnis als Base16 (Hex) und vergleichen Sie es mit dem Wert im Header X-Elido-Signature, nachdem Sie das Präfix 'sha256=' entfernt haben. Verwenden Sie eine zeitkonstante Vergleichsfunktion (z. B. hmac.compare_digest in Python, crypto.timingSafeEqual in Node.js), um Timing-Angriffe zu verhindern. Vergleichen Sie die Signatur niemals mit einem Standard-Operator für String-Gleichheit. Code-Beispiele für Node.js, Python und Go finden Sie unter /docs/guides/webhooks#verification.

Geben Sie innerhalb von 30 Sekunden HTTP 200 (oder einen beliebigen 2xx-Statuscode) zurück. Der Antwort-Body wird ignoriert – Sie können einen leeren Body oder { ok: true } zurückgeben. Wenn Ihre Verarbeitung länger als 30 Sekunden dauert, geben Sie sofort 200 zurück und verarbeiten Sie das Ereignis asynchron (in eine interne Warteschlange einreihen, 200 zurückgeben, außerhalb des Anfragepfads verarbeiten). Die Rückgabe von 4xx wird für Wiederholungszwecke genauso behandelt wie 5xx – beide lösen eine Wiederholung aus. Geben Sie 200 zurück, auch wenn das Ereignis für Ihre Integration nicht relevant ist (z. B. ein link.created-Ereignis, das Sie nicht benötigen), um unnötige Wiederholungen zu vermeiden.

Jede Webhook-Payload enthält ein event_id-Feld (UUID). Verwenden Sie dieses als Idempotenz-Schlüssel auf Ihrem Empfänger: Wenn Sie dieselbe event_id zweimal erhalten (aufgrund einer Wiederholung nach einem Teilfehler), verarbeiten Sie sie nur einmal. Speichern Sie empfangene Ereignis-IDs in einer Deduplizierungstabelle mit einer TTL von mindestens 72 Stunden (das Wiederholungsfenster). Die Wiederholungs-Payload ist identisch mit dem Original – gleiche event_id, gleicher Body – daher ist eine einfache Prüfung auf 'Habe ich diese event_id schon gesehen?' ausreichend.

Endpunkte werden nach 30 aufeinanderfolgenden Zustellungsfehlern (Nicht-2xx oder Timeout) automatisch pausiert. Dies verhindert, dass Elido einen defekten Endpunkt unbegrenzt belastet. Beheben Sie das zugrunde liegende Problem (meistens: die Endpunkt-URL hat sich geändert, der Server ist down oder das 30-Sekunden-Timeout wird aufgrund langsamer Verarbeitung überschritten), und setzen Sie den Endpunkt dann im Dashboard fort. Einmal fortgesetzt, spielt Elido Ereignisse, die während der Pause übersprungen wurden, nicht automatisch erneut ab – spielen Sie diese bei Bedarf manuell über das Zustellungsprotokoll ab.

Ja – aktivieren Sie den Raw-Click-Modus am Endpunkt. Im Raw-Click-Modus liefert Elido click.created-Ereignisse einzeln ohne Aggregationsfenster innerhalb von 2 Sekunden nach dem Klick aus. Beachten Sie, dass ein stark frequentierter Workspace im Raw-Click-Modus Tausende von Ereignissen pro Minute erzeugen kann; stellen Sie sicher, dass Ihr Empfänger diesen Durchsatz bewältigen kann. Für die meisten Analytics-Anwendungsfälle ist die standardmäßige 5-sekündige Aggregation (bis zu 100 Klicks pro Payload) ausreichend und erzeugt weit weniger HTTP-Anfragen.

Einzelne Ereignis-Payloads liegen unter 10 KB. Gebündelte Klick-Payloads (Standardmodus) können bis zu 100 Ereignisse pro Stapel enthalten, wobei die Gesamtgröße der Payload auf 100 KB begrenzt ist. Wenn ein Stapel 100 KB überschreiten würde, wird er automatisch in mehrere Zustellungen aufgeteilt. Große Metadatenfelder bei Klicks (z. B. lange Referer-URLs) werden auf 2 KB pro Feld gekürzt. Wenn Ihr Empfänger ein striktes Limit für die Payload-Größe erzwingt, konfigurieren Sie den Raw-Click-Modus (ein Ereignis pro Zustellung) anstelle des Batch-Modus.

Verwenden Sie ein Tool wie ngrok, Cloudflare Tunnel, oder localtunnel, um Ihren lokalen Server über eine öffentliche HTTPS-URL zugänglich zu machen, und registrieren Sie diese URL dann als Webhook-Endpunkt in Ihrem Test-Workspace. Alternativ können Sie die Webhook-Test-Schaltfläche im Dashboard verwenden, um eine Beispiel-Payload für einen beliebigen Ereignistyp an einen registrierten Endpunkt zu senden, ohne ein echtes Ereignis auszulösen. Die Elido-CLI (elido webhook test --event click.created --endpoint https://...) funktioniert ebenfalls für skriptgesteuerte lokale Tests.

Ereignisse, die während eines Wartungsfensters generiert werden, werden in unserem Event-Stream in die Warteschlange gestellt und nach Ende des Wartungsfensters zugestellt. Die Elido-Statusseite (status.elido.app) kündigt geplante Wartungsfenster im Voraus an. Die SLA für die Webhook-Zustellung schließt angekündigte Wartungsfenster aus. Bei einem typischen Wartungsfenster von 30–60 Minuten bedeutet das 72-Stunden-Wiederholungsfenster, dass keine Ereignisse dauerhaft verloren gehen – sie werden in der Reihenfolge ihrer Generierung zugestellt, sobald der Endpunkt wieder erreichbar ist.