Webhooks

Einrichten

Settings → API and MCP → Webhooks → Add endpoint: eine https://-Adresse und die Ereignisse, die Sie möchten. Sie erhalten ein Geheimnis, nur einmal angezeigt, um Signaturen zu prüfen.

• Edit ändert die Adresse und die Ereignisse. Das Geheimnis bleibt gleich.
• Test sendet sofort ein ping-Ereignis, damit Sie Ihren Empfänger prüfen können.
• Log zeigt die letzten Zustellungen und wie viele Versuche jede brauchte.

Ereignisse

Ereignis	Wann
issue.resolved	eine erneute Prüfung oder ein Audit findet ein Problem nicht mehr
issue.reopened	ein gelöstes Problem ist zurück
audit.finished	ein vollständiges Audit ist fertig (Seiten, offene Probleme, Werte)
score.changed	der Website-Wert hat sich nach einem Audit um 2 Punkte oder mehr bewegt
connection.broken	eine Google- oder WordPress-Verbindung funktioniert nicht mehr
recheck.failed	eine erneute Prüfung lief und das Problem ist noch da, eine geschriebene Korrektur ist noch nicht auf der Live-Seite, oder die Prüfung selbst konnte nicht laufen
write.applied	eine genehmigte Änderung (SEO-Feld, llms.txt, Regeln für KI-Crawler) wurde über WordPress oder die Shopify-App geschrieben
write.failed	eine genehmigte Änderung konnte nicht geschrieben werden
write.not_live	eine erneute Prüfung fand einen geschriebenen Wert nicht auf der Live-Seite
agentic.finished	ein Neulauf von Agentic Browsing ist fertig oder gescheitert

Zustellung

POST https://your-endpoint
Content-Type: application/json
User-Agent: MonoRanks-Webhooks/1
X-MonoRanks-Event: recheck.failed
X-MonoRanks-Delivery: <delivery id>
X-MonoRanks-Signature: sha256=<hex>

Jeder Inhalt hat id (die Zustellungs-ID), event, at, workspaceId und siteId; die meisten haben auch host und einen link zum Bildschirm in der App.

{
  "id": "…",
  "event": "recheck.failed",
  "at": "2026-10-01T09:12:00.000Z",
  "workspaceId": "…",
  "siteId": "…",
  "issue": { "id": "…", "ruleId": "SEO-ONP-011", "title": "Missing meta description", "severity": "serious", "pages": 3 },
  "crawlId": "…",
  "reason": "still_present",
  "recheck": { "present": 3, "checked": 4 },
  "link": "https://app.monoranks.com/sites/…/issues/…"
}

Was jedes Ereignis hinzufügt:

• issue.resolved, issue.reopened: issue (id, ruleId, title, severity, pages) und crawlId.
• audit.finished: crawlId, status, pagesCrawled, openIssues und score (site, health, aeo).
• score.changed: from, to, delta und since.
• connection.broken: connection (zum Beispiel gsc oder wordpress) und error.
• recheck.failed: issue, reason (still_present, not_live oder error) und recheck (present, checked).
• write.applied, write.failed, write.not_live: ein Ereignis pro genehmigtem Stapel, mit batchId, issueIds, source (wordpress oder shopify) und bis zu 50 changes, jede mit url, field, value, status und error. Bei write.not_live hat jede Änderung zusätzlich notLiveReason und liveValue (was die Seite zeigt).
• agentic.finished: jobId, url, strategy, status (done oder failed), passed von applicable, die fehlgeschlagenen Prüfungen in failing und error.

Antworten Sie innerhalb von 20 Sekunden mit einem beliebigen 2xx. Alles andere wird erneut versucht.

Die Signatur prüfen

Die Signatur ist ein HMAC-SHA256 des rohen Anfrageinhalts mit dem Geheimnis Ihres Endpunkts:

import { createHmac, timingSafeEqual } from 'node:crypto';
const expected = 'sha256=' + createHmac('sha256', SECRET).update(rawBody).digest('hex');
const ok = timingSafeEqual(Buffer.from(expected), Buffer.from(req.headers['x-monoranks-signature']));

Nutzen Sie den rohen Inhalt so, wie er ankommt, keine neu serialisierte Kopie.