Webhooks
Envía eventos a Discord, Slack, n8n o tus propios sistemas
Los webhooks empujan eventos desde Predite hacia tu propio servidor en el momento en que ocurren — sin necesidad de polling. Cuando un bot ejecuta una operación, se dispara un stop-loss o el scanner encuentra un nuevo edge, Predite envía un HTTP POST a una URL que tú controlas. Los webhooks son una función del plan Bot y se gestionan desde Configuración, en la página Webhooks.
Cómo crear un webhook
Necesitas tres cosas: una URL que acepte solicitudes POST, una etiqueta para distinguir tus webhooks y al menos un evento al que suscribirte.
Tu URL debe ser https en producción. Predite se niega a entregar a direcciones privadas, de loopback o de red interna, y no sigue redirecciones — esto protege tu cuenta de que un endpoint mal configurado se use para alcanzar el interior de nuestra infraestructura.
Eventos
Existen seis eventos. Cuatro están activos hoy:
- •ev_signal — el scanner publicó una nueva señal de Expected Value. Se envía a todos los suscriptores (no es específica del usuario). Solo se dispara cuando un modelo de IA produjo la estimación: si ningún modelo respondió (sin crédito, el tope diario de gasto, un timeout), ese mercado no genera ninguna señal, en lugar de un número de fórmula presentado como IA. Los datos incluyen ai_source, siempre "llm", para que tu código lo verifique antes de actuar.
- •arb_opportunity — se encontró una nueva oportunidad de arbitraje entre plataformas. También se envía a todos los suscriptores.
- •bot_trade_executed — uno de tus bots abrió una posición, en vivo o en paper.
- •stop_loss_triggered — una de tus salidas de protección (stop-loss, take-profit o trailing stop) cerró una posición.
Otros dos están reservados y aparecen marcados como próximamente en el dashboard — whale_move y resolution_imminent. Puedes suscribirte a ellos hoy, pero todavía no entregan nada.
Los eventos sobre tu propia actividad solo se te envían a ti. Los eventos de alcance general, de todo el mercado, se envían a todos los que estén suscritos a ellos.
Formato del payload
Cada entrega es un POST con un cuerpo JSON de esta forma:
- •event — el nombre del evento, por ejemplo bot_trade_executed
- •timestamp — cuándo ocurrió el evento, en ISO-8601
- •data — un objeto con los detalles de ese evento
Junto a él, Predite envía estas cabeceras:
- •X-Predite-Event — el nombre del evento
- •X-Predite-Timestamp — el mismo timestamp
- •X-Predite-Signature — la firma, con el formato sha256=<hex>
Cómo verificar la firma
Cada webhook tiene su propio secreto, que se muestra en el dashboard y empieza por whsec_. La firma es un HMAC-SHA256 del cuerpo crudo de la solicitud, con ese secreto como clave, codificado en hexadecimal y con el prefijo sha256=.
Para verificarla, calcula el HMAC del cuerpo que recibiste y compáralo con la cabecera X-Predite-Signature. Si no coinciden, rechaza la solicitud — no vino de nosotros. Verifica siempre antes de actuar sobre un payload, y usa siempre el cuerpo crudo, no una versión re-serializada del JSON ya parseado.
Entrega, fallos y desactivación automática
- •Cada evento se entrega en un único intento, con un timeout de 5 segundos. No hay reintentos automáticos — diseña tu endpoint para responder rápido y hacer el trabajo lento después.
- •Cualquier respuesta que no sea 2xx, un timeout o un error de conexión cuenta como fallo.
- •Tras 10 fallos consecutivos, el webhook se desactiva automáticamente y aparece como AUTO-DISABLED. Un solo éxito reinicia el contador.
- •Reactivar desde el dashboard un webhook desactivado pone a cero el contador de fallos.
Cada intento queda registrado, así que el dashboard muestra el total de entregas, los fallos consecutivos, el último éxito, el último fallo y el motivo del fallo.
Conviene saber
- •Responde 2xx en cuanto hayas guardado el evento; cualquier cosa más lenta arriesga el timeout de 5 segundos.
- •Como no hay reintentos, trata los webhooks como un canal de notificación rápido y no como un libro mayor garantizado — reconcilia contra la API pública si necesitas certeza.
- •Puedes pausar un webhook en cualquier momento en lugar de eliminarlo.