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.

Payloads firmados con HMAC Reintentos automáticos Sin polling
Webhooks · En vivo
Entrega entrante http En vivo
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

Cómo funciona

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
Eventos

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.

Guía rápida

Listo en dos pasos

Registra un endpoint y luego verifica la firma en cada solicitud. Esa es toda la integración.

1

Registra un endpoint

Crear un webhook bash
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.

2

Verifica la firma

verify.ts typescript
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.

Payload

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.

report.completed json
{
  "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).
Confiabilidad

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.

Ver planes

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í.

¿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.
¿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é 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.
¿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.
¿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.
¿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.
¿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.
¿Qué plan necesito?
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.

¿Todavía tienes preguntas? Escríbenos

Webhooks · en vivo

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.