Recibe eventos en tu cuenta de Treli en tu punto de conexión webhook para que la integración pueda activar reacciones automáticamente.
Crea un destino de evento para recibir notificaciones en un punto de conexión de webhook HTTPS. Una vez registrado el webhook, Treli enviará datos en tiempo real a tu aplicación cada vez que ocurra un evento en tu cuenta. Estos eventos se transmiten mediante HTTPS como una carga JSON que incluye un objeto de Evento.
Recibir webhooks te permite reaccionar ante eventos asincrónicos, como un pago fallido, la cancelación de una suscripción o la confirmación de un cobro recurrente exitoso.
Puedes crear un destino de evento para escuchar cualquiera de los eventos listados en Tipos de eventos.
Como obtener la firma secreta de tu punto de conexión
Ingresa a la sección Configuraciones > Desarrolladores > Webhooks. Selecciona el punto de conexión del cual deseas obtener el secreto y haz clic en Revelar firma secreta.
Protege tu punto de conexión
Debes proteger tu integración verificando que todas las solicitudes de webhook provengan realmente de Treli. Para ello, tu controlador debe validar la firma incluida en cada evento.
Cada webhook firmado incluye el encabezado x-treli-signature que contiene una marca de tiempo y una firma. La marca de tiempo aparece con el prefijo t=, mientras que la firma utiliza el prefijo v1=. Ambas deben ser verificadas antes de procesar el evento.
x-treli-signature: t=1764177654,v1=82d0f8e5c699e8d93589d2210fc74dbc1da553cfbafb7a3498fb1689d3f4d443
Treli genera firmas usando un código de autenticación de mensajes basado en hash (HMAC) con SHA-256. Para hacer la verificación. Para verificar la firma, debes completar los siguientes pasos:
Paso 1: extrae la marca de tiempo y las firmas del encabezado
Divide el encabezado con el carácter , como separador para obtener una lista de elementos. Luego, divide cada elemento con el carácter = como separador para obtener un par de prefijo y valor.
El valor del prefijo t corresponde a la marca de tiempo, mientras que v1 corresponde a la firma.
Paso 2: prepara la cadena signed_payload
La cadena signed_payload se crea concatenando:
La marca de tiempo (como cadena).
El carácter
.La carga JSON real (es decir, el cuerpo de la solicitud).
Paso 3: determina la firma esperada
Calcula un HMAC con la función hash SHA256. Usa el secreto de la firma del punto de conexión como la clave, y la cadena signed_payload como el mensaje.
Paso 4: compara las firmas
Compara la firma en el encabezado con la firma esperada. Para una correspondencia de igualdad, calcula la diferencia entre la marca de tiempo actual y la recibida, y luego decide si la diferencia está dentro de tu tolerancia.
Para protegerte contra ataques de sincronización, usa una comparación de cadenas de tiempo constante para comparar la firma esperada con la firma recibida.
Cómo prevenir ataques de reproducción
Un ataque de reproducción se produce cuando un atacante intercepta una carga válida y su firma, y luego la vuelve a transmitir. Para mitigar estos ataques, Treli incluye una marca de tiempo en el encabezado x-treli-signature. Dado que esta marca de tiempo forma parte de la carga firmada, también se verifica mediante la firma, por lo que un atacante no puede cambiar la marca de tiempo sin invalidar la firma. Si la firma es válida, pero la marca de tiempo es demasiado antigua, puedes hacer que tu aplicación rechace la carga.
Treli genera la marca de tiempo y la firma cada vez que enviamos un evento a tu punto de conexión. Si Treli reintenta un evento, se generan una firma y una marca de tiempo nuevas para el nuevo intento de entrega.