Configuración y Seguridad
Los webhooks permiten que Trébol te notifique automáticamente cuando ocurren eventos importantes, como la finalización de una verificación.- URL de entrega: Debe aceptar solicitudes HTTPS
POST
. - Autenticación: Firma HMAC-SHA256 con un secreto por webhook.
Obtención del secreto de webhook
Cada webhook tiene un secreto único que se genera automáticamente cuando lo creas. Este secreto es esencial para verificar la autenticidad de los webhooks que recibes.Cómo obtener tu secreto
El secreto del webhook se genera y se muestra únicamente una vez cuando creas el webhook a través de la API. Es crucial que guardes este secreto de forma segura, ya que no podrás recuperarlo posteriormente.1
Crear webhook con API
Usa el endpoint
POST /v2/webhooks
para crear un nuevo webhook:2
Guardar el secreto
En la respuesta, encontrarás el campo
secret
que contiene tu secreto único:¡Importante! Copia y guarda el secreto inmediatamente. Una vez que cierres esta respuesta, no podrás ver el secreto nuevamente por razones de seguridad.
3
Configurar en tu aplicación
Almacena el secreto de forma segura en tu aplicación:
Environment Variables
Configuration
Gestión de secretos
¿Qué hacer si pierdes tu secreto?
¿Qué hacer si pierdes tu secreto?
Si pierdes tu secreto de webhook, deberás crear un nuevo webhook para obtener un nuevo secreto. No es posible recuperar o regenerar el secreto de un webhook existente.
- Crea un nuevo webhook con la misma configuración
- Actualiza tu aplicación con el nuevo secreto
- Elimina el webhook anterior una vez que confirmes que el nuevo funciona correctamente
Rotación de secretos
Rotación de secretos
Para mayor seguridad, puedes implementar una rotación periódica de secretos:
- Crea un nuevo webhook con un nuevo secreto
- Actualiza tu aplicación para aceptar ambos secretos temporalmente
- Una vez confirmado que el nuevo webhook funciona, elimina el anterior
- Actualiza tu aplicación para usar solo el nuevo secreto
Secretos en diferentes entornos
Secretos en diferentes entornos
Es recomendable usar diferentes webhooks (y por tanto diferentes secretos) para cada entorno:
- Desarrollo:
whsec_dev_XXXXXXXXXXXXXXXXXXXXXXXX
- Staging:
whsec_staging_XXXXXXXXXXXXXXXXXXXXXXXX
- Producción:
whsec_prod_XXXXXXXXXXXXXXXXXXXXXXXX
Verificación de firmas de webhook
Para garantizar la seguridad y autenticidad de los webhooks, Trébol incluye una firma HMAC-SHA256 en el headerTrebol-Signature
de cada solicitud. Esta firma te permite verificar que el webhook proviene realmente de Trébol y que el payload no ha sido modificado.
Formato del header de firma
El headerTrebol-Signature
contiene múltiples elementos separados por comas:
t
: Timestamp Unix de cuando se generó la firmav1
: Firma HMAC-SHA256 del payload
Proceso de verificación
- Extraer elementos: Separa el header por comas y extrae el timestamp (
t
) y la firma (v1
) - Construir payload: Concatena el timestamp con el payload:
{timestamp}.{payload}
- Generar firma esperada: Calcula HMAC-SHA256 usando tu secreto de webhook
- Comparar firmas: Usa comparación de tiempo constante para evitar ataques de timing
Siempre verifica las firmas de webhook en producción. Nunca proceses webhooks sin verificar su autenticidad.
Ejemplos de implementación
Para mayor seguridad, también puedes verificar que el timestamp no sea demasiado antiguo (por ejemplo, no más de 5 minutos) para prevenir ataques de replay.
Direcciones IP de origen
Trébol envía todos los webhooks desde las siguientes direcciones IP:35.170.236.123
54.162.134.233
Estas IPs son estáticas y no cambiarán. Puedes configurar tu firewall para permitir únicamente estas direcciones si necesitas restricciones adicionales de seguridad.
Aunque puedes usar las IPs para validación adicional, siempre debes verificar la firma del webhook. Las IPs pueden cambiar en el futuro o ser falsificadas, pero la firma HMAC-SHA256 es la única forma garantizada de verificar la autenticidad.
Crear y gestionar webhooks por API
Usa los endpoints enAPI Reference → Gestión de Webhooks
para administrar tus webhooks.
- Crear:
POST /v2/webhooks
- Listar:
GET /v2/webhooks
- Obtener:
GET /v2/webhooks/{webhookId}
- Actualizar:
PUT /v2/webhooks/{webhookId}
- Eliminar:
DELETE /v2/webhooks/{webhookId}