Introducción
Los webhooks son la columna vertebral de las integraciones automatizadas entre Affilentra, proveedores de pagos, herramientas contables y sistemas de socios. Sin firmas seguras y protección contra reproducción, estas conexiones se convierten en una superficie de ataque: pueden producirse eventos manipulados, pagos duplicados o liquidaciones falsificadas. Este artículo muestra de forma práctica cómo los comerciantes y operadores de red en la plataforma self‑hosted Affilentra deben firmar los webhooks entrantes y salientes, prevenir ataques de reproducción y verificar las integraciones de manera robusta.
Principios básicos de la seguridad de Webhooks
La protección de los webhooks se basa en pocos pero esenciales componentes:
- Secretos confidenciales (Shared Secrets) por integración
- Comprobación de la integridad de la payload mediante firma (p. ej. HMAC)
- Protección contra reproducción mediante marca temporal y nonces
- HTTPS/TLS para el cifrado del transporte
- Registro, monitorización y rotación de claves
Affilentra admite estos mecanismos según roles: los operadores de software administran claves del sistema, los comerciantes definen secretos de integración y los socios reciben enlaces de seguimiento y registros de pago rastreables.
Webhooks entrantes: pasos de validación para comerciantes
Cuando terceros (p. ej. proveedores de pagos) envían eventos a su instancia de Affilentra, debe realizar las siguientes comprobaciones antes de desencadenar acciones:
1) Comprobación del transporte
- Aceptar solo HTTPS. Redirija las solicitudes HTTP a HTTPS o rechácelas.
2) Validación de la firma
Exija una firma HMAC que se genere sobre el cuerpo bruto (raw) de la solicitud y un secreto compartido. Nombre de encabezado recomendado: X‑Affilentra‑Signature. Procedimiento:
- Calcule HMAC‑SHA256(raw_body, secret) → hex/base64
- Compare con el valor del encabezado usando una función de comparación de tiempo constante
Importante: firme el texto bruto recibido exactamente (no el JSON parseado) para evitar problemas de canonicalization.
3) Marca temporal y protección contra reproducción
Además solicite una marca temporal en el encabezado (p. ej. X‑Affilentra‑Timestamp) y verifique:
- La marca temporal está dentro de una ventana corta (p. ej. ±300 segundos) relativa al tiempo del sistema.
- Opcional: verifique un X‑Affilentra‑Nonce adicional y almacene nonces usados durante la duración de la ventana temporal. Cada nonce solo puede aceptarse una vez.
Con marca temporal + nonce evita que una solicitud interceptada se vuelva a reproducir más tarde.
4) ID de evento e idempotencia
Exija en la carga útil un ID de evento único (p. ej. event_id). Establezca que cada ID de evento se procese una sola vez; en entregas repetidas el procesamiento debe ser idempotente y devolver un 2xx con la indicación correspondiente.
Outgoing Webhooks: Firmar eventos de Affilentra
Si su instalación de Affilentra envía eventos a proveedores de pagos, sistemas contables o socios, aplique lo siguiente: firme las solicitudes salientes de manera coherente y documente el formato para los socios de integración.
Encabezado de firma
- Incluir: X-Affilentra-Timestamp, X-Affilentra-Signature, opcional X-Affilentra-Nonce
- Cadena para firmar: concatenación de timestamp + '.' + raw_body
Flujo de ejemplo: timestamp = segundos UNIX actuales; signature = HMAC-SHA256(timestamp + '.' + raw_body, provider_secret)
Entrega y acuse de recibo
- Espere del receptor una respuesta 2xx. En caso de 5xx o errores de red: reintentos con retroceso exponencial.
- En 4xx: no realice reintentos automáticos sin revisión manual (p. ej. 401 = firma/secret erróneo).
- Registre la petición, el código de respuesta, la duración y el resultado de la verificación de la firma para auditorías.
Prevenir ataques de reproducción: conceptos prácticos
La protección contra replay combina mecanismos sencillos que, juntos, son eficaces:
- Ventana temporal corta para timestamps válidos (p. ej. 2–5 minutos).
- Almacenamiento persistente de nonces/IDs de evento usados durante la duración de la ventana temporal.
- Procesamiento idempotente mediante verificaciones de ID de evento.
- Detección de entregas múltiples: clases de registro diferenciadas (advertencia vs. error).
En un entorno self-hosted como Affilentra puede almacenar caches de nonce en Redis o en la base de datos con TTL; lo importante es que el almacenamiento sea lo suficientemente rápido para verificar solicitudes paralelas de manera consistente.
Verificación y manejo de errores
Los casos de error deben ser transparentes y manejables:
- En errores de firma: 401 Unauthorized + registro con Request-ID, pero sin incluir el contenido de la carga útil en los logs si hay datos sensibles.
- En errores de timestamp/nonce: 400 Bad Request con una descripción clara del error en el body.
- En entregas repetidas: 200 OK si el evento ya fue procesado, y devolver un indicador, p. ej. {"status":"duplicate","event_id":...}.
- Alerta: ante una tasa inusualmente alta de errores de firma o timestamp, generar alertas automáticas para operadores y comerciantes.
Recomendaciones operativas y gestión de secretos
La gestión basada en roles es central en Affilentra: los operadores de software administran la plataforma, los comerciantes configuran los secretos de integración y los socios usan claves dedicadas. Medidas recomendadas:
- Un secret distinto por integración; no reutilizar.
- Almacenar los secrets en variables de entorno o en gestores de secretos (p. ej., HashiCorp Vault); nunca en el código ni en repositorios públicos.
- Rotación regular de claves (p. ej., cada 90 días) con una fase de transición en la que se aceptan la clave antigua y la nueva.
- Registros de auditoría para el uso y la rotación de claves.
- Restringir el acceso por IP a los endpoints de webhook cuando sea posible (lista blanca) — como medida complementaria, no como sustituto de las firmas.
Ejemplo práctico: flujo HMAC‑SHA256 (conceptual)
Así podría ser un flujo mínimo de firma en Affilentra:
- Remitente: genera timestamp, raw_body y nonce; signature = HMAC‑SHA256(timestamp + '.' + raw_body, shared_secret).
- Remitente: envía un POST al destinatario con los encabezados X‑Affilentra‑Timestamp, X‑Affilentra‑Nonce, X‑Affilentra‑Signature y el raw_body.
- Receptor (Affilentra): verifica TLS, lee el raw_body, valida el timestamp frente al reloj del sistema, comprueba la caché de nonces, calcula el HMAC y compara las firmas en tiempo constante, valida event_id y procesa de forma idempotente.
Estos pasos se presentan de forma deliberadamente sencilla; en la implementación debe asegurarse el uso de comparaciones en tiempo constante, nonces seguros generados aleatoriamente y registros de errores robustos.
Indicaciones por roles para usuarios de Affilentra
- Comerciantes: Cree secrets separados por proveedor de pagos (Payout‑Provider) y por herramienta contable. Utilice las configuraciones de Affilentra para hacer obligatorias las exigencias de firma.
- Operadores de red: Proporcione un monitoreo centralizado y exija a los socios encabezados que permitan comprobar la integridad. Use las ediciones PRO & NETWORK para una asignación granular de permisos.
- Socios/Publicadores: Verifiquen localmente los webhooks salientes de Affilentra antes de su procesamiento y documenten los encabezados esperados y las event‑IDs.
Conclusión y siguiente paso
Operar webhooks de forma segura requiere la aplicación consistente de firmas, protección contra replay y controles operativos. En la plataforma Affilentra self‑hosted puede configurar estos mecanismos basados en roles para asegurar de forma fiable las integraciones con Payout‑Providers, herramientas contables y sistemas de socios. Si busca una solución segura, autoalojada, con licencia permanente y sin participación en los ingresos, considere las ediciones PRO & NETWORK.
Actúe ahora: Elija cómo empezar y descubra cómo Affilentra protege de forma robusta sus integraciones de webhooks: https://affilentra.de
Siguiente paso
Probar Affilentra
Plataforma unificada que reúne la entrega de productos, el seguimiento, la validación de conversiones, el cálculo de comisiones y los pagos con roles claramente separados; opción de instalación autohospedada con licencia perpetua sin participación en los ingresos; los comerciantes mantienen el control sobre productos, condiciones y materiales publicitarios; los socios reciben enlaces de seguimiento personales e historiales de pagos verificables.