Webhooks

Configuración

Settings → API and MCP → Webhooks → Add endpoint: una dirección https:// y los eventos que quieras. Recibes un secreto, que se muestra una sola vez, para comprobar las firmas.

• Edit cambia la dirección y los eventos. El secreto sigue igual.
• Test envía enseguida un evento ping, para que puedas comprobar tu receptor.
• Log muestra los últimos envíos y cuántos intentos necesitó cada uno.

Eventos

Evento	Cuándo
issue.resolved	una revisión o auditoría ya no encuentra un problema
issue.reopened	un problema resuelto volvió
audit.finished	terminó una auditoría completa (páginas, problemas abiertos, puntuaciones)
score.changed	la puntuación del sitio web cambió 2 puntos o más tras una auditoría
connection.broken	una conexión de Google o WordPress dejó de funcionar
recheck.failed	una revisión se ejecutó y el problema sigue ahí, una corrección escrita aún no está en la página publicada, o la revisión no se pudo ejecutar
write.applied	un cambio aprobado (campo SEO, llms.txt, reglas para rastreadores de IA) se escribió mediante WordPress o la app de Shopify
write.failed	un cambio aprobado no se pudo escribir
write.not_live	una revisión no encontró un valor escrito en la página publicada
agentic.finished	una nueva ejecución de la prueba de navegación por agentes terminó o falló

Envío

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>

Cada cuerpo tiene id (el id del envío), event, at, workspaceId y siteId; la mayoría también tiene host y un link a la pantalla de la 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/…"
}

Lo que añade cada evento:

• issue.resolved, issue.reopened: issue (id, ruleId, title, severity, pages) y crawlId.
• audit.finished: crawlId, status, pagesCrawled, openIssues y score (site, health, aeo).
• score.changed: from, to, delta y since.
• connection.broken: connection (por ejemplo gsc o wordpress) y error.
• recheck.failed: issue, reason (still_present, not_live o error) y recheck (present, checked).
• write.applied, write.failed, write.not_live: un evento por lote aprobado, con batchId, issueIds, source (wordpress o shopify) y hasta 50 changes, cada uno con url, field, value, status y error. En write.not_live, cada cambio tiene además notLiveReason y liveValue (lo que muestra la página).
• agentic.finished: jobId, url, strategy, status (done o failed), passed de applicable, las comprobaciones que fallan (failing) y error.

Responde con cualquier 2xx en menos de 20 segundos. Cualquier otra respuesta se vuelve a intentar.

Comprobar la firma

La firma es un HMAC-SHA256 del cuerpo sin procesar de la solicitud con el secreto de tu endpoint:

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']));

Usa el cuerpo tal como llega, no una copia serializada de nuevo.