Saltar al contenido principal
Un webhook es Reval avisándole a tu servidor que algo pasó: se cobró un ciclo, un cobro falló, un cliente pausó o canceló. Es el complemento de la API: la API se consulta, los webhooks te avisan. Todo se configura en Reval → Integraciones → Webhooks.
Los webhooks son best-effort respecto del flujo principal: un endpoint caído nunca frena un cobro ni la creación de un pedido. Reval encola el envío, lo intenta aparte y lo reintenta si falla.

Configurar un endpoint

  1. En Reval → Integraciones → Webhooks, pegá la URL de tu servidor (tiene que ser https) y elegí a qué eventos se suscribe.
  2. Guardá. Reval genera un secreto de firma (whsec_…) para ese endpoint: lo ves con «Mostrar» y lo copiás a tu servidor.
  3. Usá «Enviar prueba»: tu endpoint recibe un evento test y el admin muestra el resultado (código HTTP o error).
Podés tener hasta 10 endpoints por tienda, cada uno con su propia lista de eventos y su propio secreto. Pausar un endpoint deja de enviarle eventos sin borrar su configuración ni su historial; Borrar elimina las dos cosas.
Los payloads incluyen datos personales del suscriptor (email, nombre, ciudad). Por eso solo se aceptan URLs https, y Reval rechaza direcciones internas o privadas (localhost, IPs de red local, hosts sin dominio). El nombre se vuelve a verificar al momento de cada envío, después de resolver el DNS: si pasa a apuntar a una dirección privada, la entrega se descarta con error.

Los eventos

Son los mismos 15 eventos de suscripción que Reval envía a Klaviyo y Shopify Flow, con los mismos datos, más los 3 de checkouts y carritos abandonados, que no tienen suscripción todavía y salen solo a Klaviyo y a webhooks. El topic de cada envío es subscription.<evento>, checkout.<evento> o cart.<evento>:

El envío

Cada entrega es un POST a tu URL con un cuerpo JSON y estos headers:
data lleva las mismas propiedades que reciben Klaviyo y Shopify Flow: identidad del cliente, producto, montos (crudos y formateados), plan, número de ciclo, fechas, dirección de envío y links al portal, más las propiedades propias de cada evento (reason, source, detail, held_product_names, merged_with_subscription_ids, etc.).

Las propiedades de data

Las propiedades son las mismas para todos los eventos, más las propias de cada uno. Van en snake_case; los montos crudos son números y los _formatted son strings listos para un email. Las etiquetas (frequency_label, next_payment_date_label, reason, reason_text) salen en el idioma configurado de la tienda (español o portugués); para condiciones usá las propiedades crudas (status, frequency_type, source, fechas ISO) y reason_key, que no cambian con el idioma. Y además, según el evento: Respondé cualquier 2xx lo antes posible —idealmente antes de procesar— y procesá en segundo plano. Reval espera 10 segundos; después corta y cuenta el intento como fallido. Las redirecciones no se siguen.

Verificar la firma

Cada envío va firmado con el secreto del endpoint para que puedas confirmar que lo mandó Reval y que no fue alterado:
  • t es la hora del envío en segundos Unix.
  • v1 es HMAC-SHA256(secreto, "<t>.<cuerpo crudo>") en hexadecimal.
Firmá el cuerpo crudo tal como llegó (los bytes, no un JSON re-serializado), compará en tiempo constante y rechazá firmas con más de 5 minutos de diferencia:
Si creés que el secreto se filtró, borrá el endpoint y creá uno nuevo: tiene secreto nuevo. Los eventos que ya estaban en cola para el endpoint borrado se descartan.

Reintentos

Si tu servidor responde algo que no es 2xx, no responde en 10 segundos o no se puede resolver, Reval reintenta con espera creciente: Después del séptimo intento la entrega queda Fallida. No se pierde: la ves en el registro y la podés reenviar cuando tu servidor vuelva. Como los reintentos mantienen el mismo X-Reval-Delivery, un endpoint que respondió 2xx tarde (por ejemplo, justo después del timeout) puede recibir el mismo evento dos veces. Guardá el ID y descartá los repetidos.

Registro de entregas

En cada endpoint, «Ver entregas» muestra las últimas 50: evento, fecha, cantidad de intentos, estado (Pendiente, En curso, Entregado, Fallido), código HTTP de la última respuesta y el error si lo hubo. Cada fila tiene «Reenviar», que vuelve a mandar exactamente el mismo payload con el mismo ID.

Preguntas frecuentes

¿Se envían eventos de antes de crear el endpoint? No. Un endpoint recibe los eventos que ocurren desde que existe y está activo. Para el histórico está la API. ¿Puedo recibir solo cancelaciones? Sí: al crear o editar el endpoint, marcá solo los eventos que te interesan. ¿Qué pasa si pauso el endpoint? Los eventos que ocurran mientras está pausado no se le envían ni se guardan. Al reanudarlo recibe los nuevos. ¿Mi endpoint puede estar en Zapier, Make o n8n? Sí, cualquier URL https pública sirve. Esas herramientas suelen responder 2xx de inmediato, que es justo lo que Reval espera.