Deja de hacer polling: nosotros te avisamos.
Suscribe un endpoint HTTPS y Rank Prompt hace POST en el momento en que un reporte o una ejecución programada termina en ChatGPT, Perplexity, Google AI Mode, Claude, Gemini y Grok. Firmado, reintentado y reproducible, para que tus paneles, tu warehouse y tus alertas reaccionen en segundos, no según un cron.
- Payloads firmados con HMAC
- Reintentos automáticos
- Sin polling
POST /webhooks/rankprompt HTTP/1.1
Host: api.yourbrand.com
X-RP-Event: report.completed
X-RP-Event-Id: evt_9b2c7e1f…
X-RP-Signature: t=1751198400,v1=5f1e9c8a2b…
Content-Type: application/json
{
"id": "evt_9b2c7e1f…",
"type": "report.completed",
"api_version": "v1",
"data": { "report_id": "f4c1…", "brand_id": "a1b2…", "status": "completed" }
}Cómo funciona
Un envío, no un sondeo
Registras un endpoint una vez y eliges los momentos que te importan. Apenas termina un reporte o una ejecución programada, se lo decimos a tus sistemas, y seguimos intentando hasta que lo reciban.
Apúntalo a Slack, a la carga de tu warehouse o a los dashboards de tus clientes, y se actualizan solos en cuanto llegan nuevas respuestas de IA. Los creas, rotas, inspeccionas y reenvías desde Developers > Webhooks, o por API, así viven en código junto al resto de tu stack.
- cuándo Apenas termina el trabajo
- prueba Firmado, sabes que viene de nosotros
- si estás caído Reintentamos y luego te avisamos por email
- configuración El dashboard, o una llamada a la API por endpoint
Seis momentos para reaccionar
Solo avisamos cuando el trabajo termina: los reportes que corres y los programados, los artículos que publicas y, en Agency Plus, los leads que trae tu widget. Sin avisos de progreso que hagan ruido.
Un reporte está listo
Actualiza el dashboard del cliente, publica el nuevo puntaje de visibilidad en Slack o carga las respuestas en tu warehouse.
Un reporte falló
Alerta al equipo antes de que el cliente lo note, y vuelve a correrlo sin que nadie revise a mano.
Terminó una ejecución programada
Manda los números de la semana a cada interesado apenas existen, sin tener que dispararlo.
Falló una ejecución programada
Sabes por qué se detuvo y lo arreglas antes del próximo reporte.
Un artículo se publica, cambia o se retira
article.published, article.updated y article.unpublished, configurados en el dashboard: reconstruye un sitio estático, avisa a un editor o publica el enlace en Slack o Discord.
Llega un lead desde tu widget
En Agency Plus, lead.created, lead.report_ready, lead.report_failed y lead.claimed llegan a tu CRM en el momento en que ocurren. Se configuran en el dashboard.
Listo en dos pasos
Registra un endpoint y luego verifica la firma en cada solicitud. Esa es toda la integración.
Registra un endpoint
curl -X POST https://api.rankprompt.com/v1/brands/$BRAND_ID/webhooks \
-H "Authorization: Bearer $RANKPROMPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.yourbrand.com/webhooks/rankprompt",
"events": ["report.completed", "schedule.run.completed"],
"description": "Production listener"
}' El secret de firma vuelve exactamente una vez, guárdalo ahora. ¿Necesitas una clave primero? Genera una en la página de Desarrolladores.
Verifica la firma
import crypto from "node:crypto";
// Verify the X-RP-Signature header against the RAW request body.
export function isFromRankPrompt(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const signed = parts.t + "." + rawBody;
const expected = crypto.createHmac("sha256", secret).update(signed).digest("hex");
// Constant-time compare against v1 (also accept v0 during a secret rotation).
const match = crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
// Reject replays: require a recent timestamp (within 5 minutes).
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
return match && fresh;
} Siempre firma sobre el cuerpo de la solicitud sin procesar, antes de cualquier parseo de JSON, y compara en tiempo constante. Durante una rotación de secreto, revisa también la firma v0.
Construido para entregar, y para verificar
Reintentos, autodesactivación, idempotencia y rotación firmada, para que un endpoint inestable nunca te haga perder un evento y un secreto filtrado nunca te cueste downtime.
Reintentos automáticos
Las entregas fallidas reintentan con backoff de 30s → 2m → 10m → 1h → 6h → 24h: hasta siete intentos antes de descartar una entrega.
Autodesactivación + alerta
Tras 20 fallos consecutivos desactivamos el endpoint y avisamos por correo al dueño de la marca. Reactívalo con un PATCH una vez resuelto.
Entrega al menos una vez
La entrega es al menos una vez tras el éxito. Deduplica con X-RP-Event-Id y mantén tus handlers idempotentes. El orden por endpoint se conserva.
Rotación sin downtime
Rota el secreto de firma cuando quieras. El secreto anterior sigue firmando como v0 por 24h, así actualizas tu verificador sin ningún hueco.
Registro de entregas y repetición
Inspecciona intentos recientes (estado, código de respuesta, error) y repite cualquier entrega pasada directo desde la API.
Solo HTTPS público
Los endpoints deben ser URLs públicas https://. Los objetivos privados, loopback y no enrutables se rechazan (protección SSRF).
Plan
Los webhooks están incluidos en todo plan Starter o superior, o en un plan de API independiente. Es el mismo entitlement que la API pública /v1 y el servidor MCP.
Gestiona endpoints con el permiso write:webhooks; inspecciona entregas con read:webhooks.
Preguntas frecuentes
Preguntas sobre webhooks
Todo lo que preguntan los equipos antes de conectar un endpoint. Escríbenos si tu pregunta no está aquí.
¿Todavía tienes preguntas? Escríbenos
¿En qué se diferencian los webhooks de hacer polling a la API?
Dejas de hacer polling del estado de un reporte desde un worker. Rank Prompt hace POST a tu endpoint en el momento en que un reporte o una ejecución programada llega a un estado terminal, así que tu stack reacciona en segundos en vez de según un cron.
¿A qué eventos me puedo suscribir?
A cuatro: report.completed, report.failed, schedule.run.completed y schedule.run.failed. Puedes correr hasta 5 endpoints activos por marca, cada uno suscrito a cualquier subconjunto de eventos.
¿Cómo verifico que una solicitud realmente vino de Rank Prompt?
Cada solicitud lleva un header X-RP-Signature con la forma t=<timestamp>,v1=<hmac>. Recalcula un HMAC-SHA256 de "{timestamp}.{cuerpo sin procesar}" con tu secreto de firma y compáralo con v1 en tiempo constante. Rechaza timestamps antiguos para prevenir repeticiones.
¿Qué hay en el payload?
Un sobre JSON pequeño: id (evt_…), type, api_version, created_at y un bloque data. El bloque data lleva los ids (report_id, brand_id, …); trae el recurso completo desde /v1 cuando necesites el detalle.
¿Qué pasa si mi endpoint está caído?
Reintentamos con backoff exponencial (30s, 2m, 10m, 1h, 6h, 24h) hasta siete intentos. Tras 20 entregas fallidas consecutivas el endpoint se autodesactiva y avisamos por correo al dueño de la marca. Resuélvelo y reactívalo con un PATCH.
¿Cómo roto el secreto de firma?
Haz POST a la ruta de rotación de secreto del endpoint. El secreto nuevo se devuelve una sola vez y el anterior sigue firmando entregas como v0 durante una superposición de 24 horas, así puedes actualizar tu verificador sin downtime.
¿Se puede entregar el mismo evento dos veces?
Sí. La entrega es al menos una vez tras el éxito, así que diséñalo pensando en eso: deduplica con el id del evento (X-RP-Event-Id) y haz que tu handler sea idempotente. Las entregas a un mismo endpoint conservan el orden.
¿Qué plan necesito?
Los webhooks están incluidos en todo plan Starter o superior, o en un plan de API independiente. A diferencia de la API /v1 y el servidor MCP, que puede usar cualquier plan, los webhooks arrancan en Starter.
Primero tu reporte de visibilidad en IA gratis · prueba de 7 días en cualquier plan
Conecta Rank Prompt a tu stack
Empieza una prueba gratis, registra un endpoint y deja que los eventos de reportes y programaciones fluyan directo a tus paneles, tu warehouse y tus alertas.