Guía de integración
Configura los webhooks de Rank Prompt
Deja de consultar. Rank Prompt llama a tu endpoint en cuanto un reporte o una ejecución programada termina, o falla, con un payload firmado en el que tu servidor puede confiar.
Rank Prompt lee
- El código de respuesta de tu endpoint
Rank Prompt envía
- Tipo e id del evento
- Payload del reporte o de la ejecución
- Firma HMAC
- Id de la entrega
Rank Prompt Qué hace
- Envía
report.completed,report.failed,schedule.run.completedyschedule.run.faileda tu endpoint, por marca. - Firma cada entrega con HMAC para que puedas probar que viene de Rank Prompt.
- Reintenta una entrega fallida a los 30 segundos, 2 minutos, 10 minutos, 1 hora, 6 horas y 24 horas.
- Rota el secreto de firma sin cortes, y desactiva un endpoint después de 20 fallas seguidas.
- También publica en Slack o Discord: elige el tipo de destino y cada evento llega como un mensaje escrito para el canal.
- Suscribe un endpoint de marca también a los eventos de artículos:
article.published,article.updatedyarticle.unpublished. - Envía una entrega de prueba cuando quieras, firmada como una real, con la respuesta y el tiempo que tardó a la vista.
Antes de empezar
Plan Desde Starter
- Un endpoint HTTPS público en tu servidor que responda rápido con un código 2xx.
- Un lugar para guardar el secreto de firma, como tu gestor de secretos.
- Hasta 5 endpoints activos por marca.
Webhooks: configuración en 4 pasos
-
Paso 1
Abre Desarrolladores, Webhooks
En Rank Prompt, abre Desarrolladores, elige la pestaña Webhooks y la marca.
-
Paso 2
Agrega tu endpoint
Haz clic en Nuevo webhook, escribe la URL https y elige los eventos que debe recibir.
-
Paso 3
Guarda el secreto de firma
Copia el secreto en tu servidor. Cada entrega trae
X-RP-Signaturecon una marca de tiempo y una firmav1; recalcúlala sobre el cuerpo crudo y compara. -
Paso 4
Procesa las entregas
Responde rápido con un 2xx y después haz el trabajo. Usa
X-RP-Event-Idpara ignorar un reintento que ya procesaste.
Webhooks: errores y soluciones
Estos son los mensajes que muestra la app, palabra por palabra, y lo que resuelve cada uno.
-
Se alcanzó el máximo de 5 webhooks activos por marca.
Desactiva o borra un endpoint que ya no uses, o manda varios tipos de evento al mismo endpoint.
-
Desactivamos el webhook de Mercari (JSON firmado, b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d) después de 20 entregas fallidas consecutivas. Corrige el endpoint y vuelve a activarlo para reanudar los eventos.
Haz que el endpoint vuelva a responder con un 2xx y reactívalo en la pestaña Webhooks. Las entregas descartadas se pueden reenviar desde ahí.
¿A qué eventos me puedo suscribir?
report.completed, report.failed, schedule.run.completed y schedule.run.failed, además de article.published, article.updated y article.unpublished, por marca. En Agency Plus el dueño de la cuenta también puede crear endpoints de cuenta para lead.created, lead.report_ready, lead.report_failed y lead.claimed, en Developers, Webhooks, en Cuenta (/developers?tab=webhooks&scope=account).
¿Qué pasa si mi endpoint está caído?
La entrega se reintenta seis veces durante más o menos un día: a los 30 segundos, 2 minutos, 10 minutos, 1 hora, 6 horas y 24 horas. Después de 20 fallas seguidas el endpoint se desactiva hasta que lo vuelvas a activar.
¿Cómo verifico una entrega?
Recalcula el HMAC de la marca de tiempo y del cuerpo crudo con tu secreto de firma y compáralo con la firma de X-RP-Signature. La documentación para desarrolladores tiene el código.
¿Qué plan necesito?
Los webhooks empiezan en Starter, a $49 al mes, o vienen con un plan de API independiente.
¿Puedo enviar eventos a Slack o Discord?
Sí. Elige Slack o Discord como tipo de destino y pega la URL del webhook entrante del canal: cada evento llega como un mensaje para ese canal, en el idioma del dueño.
¿Cómo pruebo un endpoint?
Haz clic en Enviar prueba en el endpoint. La prueba va firmada como una entrega real, lleva test: true, nunca cuenta para la desactivación automática y muestra la respuesta y el tiempo de tu endpoint. Un Replay desde el registro de entregas envía una entrega nueva con un id de entrega nuevo y el mismo id de evento y cuerpo que la primera.
¿Es así como publico artículos en Zapier o Make?
No, para eso está el destino webhook: envía el artículo completo, firmado, al publicar, y registra dónde quedó publicado. Los webhooks de aquí avisan a tus herramientas que algo pasó.
En marcha en pocos minutos
Crea una cuenta gratis, sigue los pasos de arriba y mira qué le suma la conexión a tu visibilidad en IA.