Webhooks

Webhooks schicken dir Ereignisse in dem Moment, in dem sie passieren, statt dass du die REST-API abfragst. Registriere einen HTTPS-Endpunkt und CrunchJunkie sendet bei jedem abonnierten Ereignis eine signierte JSON-Nutzlast per POST dorthin — so kannst du bei einem Sichtbarkeitsrückgang eine Slack-Warnung auslösen, einen Workflow starten, wenn ein Scan fertig ist, oder Ereignisse in deine eigene Datenbank spiegeln, ohne einen eigenen Cron. Jede Zustellung ist signiert (du kannst also beweisen, dass sie von uns stammt), wird bei kurzem Ausfall automatisch wiederholt und protokolliert. Webhooks sind in den kostenpflichtigen Plänen (Pro, Agency, Scale) verfügbar, und nur Inhaber oder Admins eines Workspace können sie verwalten.

Öffne Einstellungen → Webhooks und füge die HTTPS-URL deines Empfängers hinzu (http:// wird abgelehnt). Wähle, welche Ereignisse er empfangen soll — alle oder eine bestimmte Auswahl — und optional eine Bezeichnung. Beim Speichern zeigen wir das Signatur-Geheimnis genau einmal. Es sieht aus wie whsec_… — kopiere es jetzt in deinen Empfänger; wir können es nicht erneut anzeigen, nur gegen ein neues rotieren. Mit „Test senden“ feuerst du ein Beispiel-Ereignis an deinen Endpunkt und prüfst, dass er die Zustellung annimmt und verifiziert, bevor du dich darauf verlässt.

Wir senden eine JSON-Hülle im Standard-Webhooks-Format per POST: { "id": "msg_…", "type": "signal.created", "timestamp": "2026-08-28T10:00:00.000Z", "api_version": "2026-08-01", "data": { … } } • id — eine eindeutige Nachrichten-ID; auch als Header webhook-id gesendet. Nutze sie als Idempotenz-Schlüssel, damit eine Wiederholung nie doppelt verarbeitet wird. • type — der Ereignistyp (siehe unten). • data — das vollständige Ereignisobjekt, sodass du selten einen zusätzlichen API-Aufruf brauchst. Antworte mit einem beliebigen 2xx-Status zur Bestätigung. Alles andere (oder ein Timeout nach 15 Sekunden) gilt als Fehlschlag und wird wiederholt.

Drei Header begleiten jede Zustellung: webhook-id, webhook-timestamp (Unix-Sekunden) und webhook-signature. Die Signatur ist HMAC-SHA256 über die Zeichenkette `{id}.{timestamp}.{body}`, base64-kodiert, mit Präfix v1,. Das ist das Standard-Webhooks-Schema, jede svix-kompatible Bibliothek verifiziert es also — oder verifiziere es von Hand: import crypto from "node:crypto"; function verify(secret, headers, body) { const key = Buffer.from(secret.replace(/^whsec_/, ""), "base64"); const signed = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${body}`; const expected = "v1," + crypto.createHmac("sha256", key).update(signed).digest("base64"); return headers["webhook-signature"].split(" ").some(s => crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected))); } Verifiziere immer gegen den ROHEN Request-Body (vor dem JSON-Parsen) und weise Zustellungen ab, deren webhook-timestamp älter als fünf Minuten ist, um Replays zu verhindern.

Aktuelle Ereignistypen: • signal.created — ein neues Signal wurde erkannt (Sichtbarkeitsrückgang, Überholung durch Wettbewerber, GEO-Rückgang, tote Quelle, kanalübergreifend). Nur wirklich neue Signale feuern; ein dauerhaft wahres Ergebnis spammt dich nicht zu. • scan.completed — ein KI-Sichtbarkeits-Scan hat einen Endzustand erreicht; data.status ist done, stopped oder error. Schlägt eine Zustellung fehl, wiederholen wir mit exponentiellem Backoff — nach 5s, dann 5m, 30m, 2h, 5h und 10h — bis zu acht Versuche über mehr als einen Tag; dieselbe webhook-id wird bei jeder Wiederholung genutzt. Nach vielen aufeinanderfolgenden Fehlschlägen wird ein Endpunkt automatisch deaktiviert (mit Grund in den Einstellungen), damit eine dauerhaft tote URL keinen Traffic mehr erzeugt; aktiviere ihn nach der Behebung wieder. Rotiere das Signatur-Geheimnis jederzeit auf demselben Bildschirm — das alte Geheimnis funktioniert sofort nicht mehr, aktualisiere also deinen Empfänger im selben Schritt.