Deja de hacer polling. Nosotros te enviamos.
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.
POST /webhooks/rankprompt HTTP/1.1
Host: your-app.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" }
} Firmado con HMAC-SHA256 · verificado contra tu secreto
Un envío, no un sondeo
Registra un endpoint una sola vez con la API pública y elige los eventos que te importan. Cuando un reporte o una ejecución programada llega a un estado terminal, hacemos POST de un sobre JSON firmado a tu URL, reintentando hasta que funcione.
El sobre es intencionalmente pequeño: lleva el tipo de evento y los ids que necesitas para hacer GET el recurso completo desde /v1. No hay un interruptor en la app, los webhooks se gestionan completamente por la API.
- transporte
- HTTPS POST (solo URLs públicas)
- firma
- X-RP-Signature · HMAC-SHA256
- eventos
- 4 tipos · reporte y programación
- entrega
- al menos una vez · con reintento · reproducible
Cuatro eventos, solo estados terminales
Emitimos cuando el trabajo realmente termina, completado o fallido, tanto para reportes bajo demanda como para ejecuciones programadas. Sin avisos de progreso ruidosos.
report.completed Un reporte manual o programado terminó de analizar. Lleva report_id, brand_id, status y conteos de prompts.
report.failed Una ejecución de reporte falló antes de terminar. Lleva report_id, brand_id y status.
schedule.run.completed Un lote programado terminó. Lleva scheduled_run_id, scheduled_report_id, brand_id y conteos por región.
schedule.run.failed Un lote programado falló. Incluye un failure_reason cuando hay uno disponible.
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://your-app.com/webhooks/rankprompt",
"events": ["report.completed", "schedule.run.completed"],
"description": "Production listener"
}'
# 201 Created. The signing secret is shown exactly once, so store it now:
# { "id": "whk_…", "secret": "whsec_…", "secret_version": 1, "is_active": true } 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.
Un sobre predecible
Cada evento envía la misma forma de sobre. El bloque de datos lleva los ids; trae el recurso completo desde /v1 cuando necesites más.
{
"id": "evt_9b2c7e1f4a8d4c0e9f2b6a1d3c5e7f90",
"type": "report.completed",
"api_version": "v1",
"created_at": "2026-06-29T12:00:00.482913+00:00",
"data": {
"report_id": "f4c1e2a0-1b2c-3d4e-5f60-7a8b9c0d1e2f",
"brand_id": "a1b2c3d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
"scheduled_report_id": null,
"status": "completed",
"total_prompts_count": 24,
"ranked_prompts_count": 24
}
} Headers de la solicitud
- X-RP-Event
- El tipo de evento, por ejemplo report.completed.
- X-RP-Event-Id
- Id estable del evento lógico (evt_…). Usa esto para deduplicar.
- X-RP-Delivery-Id
- Id único para este intento de entrega individual.
- X-RP-Signature
- Timestamp + HMAC-SHA256: t=…,v1=… (y v0=… durante una rotación).
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 sobre webhooks
Todo lo que preguntan los equipos antes de conectar un endpoint. Escríbenos si tu pregunta no está aquí.
¿En qué se diferencian los webhooks de hacer polling a la API?
¿Cómo verifico que una solicitud realmente vino de Rank Prompt?
¿Qué pasa si mi endpoint está caído?
¿Se puede entregar el mismo evento dos veces?
¿A qué eventos me puedo suscribir?
¿Qué hay en el payload?
¿Cómo roto el secreto de firma?
¿Qué plan necesito?
¿Todavía tienes preguntas? Escríbenos
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.