Seguridad de Webhooks

Descripción General

Asegurar tus endpoints de webhook es crítico para garantizar que las solicitudes de webhook provienen de Gu1 y no de actores maliciosos. Esta guía cubre cómo verificar firmas de webhook, implementar mejores prácticas de seguridad y evitar errores comunes de seguridad.

Verificación de Firmas

Gu1 firma todas las solicitudes de webhook con una firma HMAC SHA-256 usando tu secreto de webhook. La firma se envía en el encabezado X-Webhook-Signature, permitiéndote verificar que la solicitud es auténtica.

Cómo Funciona la Verificación de Firmas

Gu1 genera una firma: Al enviar un webhook, Gu1 crea un hash HMAC SHA-256 del cuerpo de la solicitud sin procesar usando tu secreto de webhook
La firma se envía en el encabezado: La firma se incluye en el encabezado X-Webhook-Signature
Tu servidor recalcula: Tu endpoint recalcula la firma usando el mismo secreto y cuerpo sin procesar
Comparar firmas: Si las firmas coinciden, el webhook es auténtico

Siempre verifica las firmas de webhook en producción. Sin verificación, cualquiera puede enviar webhooks falsos a tu endpoint y potencialmente comprometer tu sistema.

Ejemplos de Verificación de Firmas

Node.js (Express)

Node.js

const express = require('express');
const crypto = require('crypto');

const app = express();

// IMPORTANTE: Almacenar cuerpo sin procesar para verificación de firmas
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString('utf8');
  }
}));

app.post('/webhooks/gu1', async (req, res) => {
  try {
    // Obtener firma del encabezado
    const signature = req.headers['x-webhook-signature'];
    const webhookSecret = process.env.GU1_WEBHOOK_SECRET;

    // Verificar firma
    if (!verifySignature(req.rawBody, signature, webhookSecret)) {
      console.error('Invalid webhook signature');
      return res.status(401).json({ error: 'Invalid signature' });
    }

    // Procesar webhook
    const { event, timestamp, payload } = req.body;
    await handleWebhook(event, payload);

    // Devolver 200 para confirmar recepción
    res.status(200).json({ success: true });
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: error.message });
  }
});

/**
 * Verificar firma HMAC SHA-256
 */
function verifySignature(rawBody, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return signature === expectedSignature;
}

app.listen(3000);

Crítico: Debes verificar la firma usando el cuerpo de solicitud sin procesar antes de que se analice como JSON. Si verificas contra el cuerpo JSON analizado (ej., JSON.stringify(req.body)), la firma no coincidirá porque el formato JSON puede diferir.

Python (Flask)

Python

from flask import Flask, request, jsonify
import hmac
import hashlib
import os
import logging

app = Flask(__name__)

@app.route('/webhooks/gu1', methods=['POST'])
def gu1_webhook():
    try:
        # Obtener firma del encabezado
        signature = request.headers.get('X-Webhook-Signature')
        webhook_secret = os.getenv('GU1_WEBHOOK_SECRET')

        # Obtener cuerpo sin procesar para verificación de firmas
        raw_body = request.get_data(as_text=True)

        # Verificar firma
        if not verify_signature(raw_body, signature, webhook_secret):
            logging.error('Invalid webhook signature')
            return jsonify({'error': 'Invalid signature'}), 401

        # Analizar payload
        payload = request.json
        event = payload.get('event')
        data = payload.get('payload')

        logging.info(f'Received webhook: {event}')

        # Procesar el webhook
        handle_webhook(event, data)

        return jsonify({
            'success': True,
            'message': 'Webhook received'
        }), 200

    except Exception as e:
        logging.error(f'Webhook error: {e}')
        return jsonify({
            'success': False,
            'error': str(e)
        }), 500

def verify_signature(raw_body: str, signature: str, secret: str) -> bool:
    """Verificar firma HMAC SHA-256"""
    expected_signature = hmac.new(
        secret.encode('utf-8'),
        raw_body.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(signature, expected_signature)

def handle_webhook(event: str, data: dict):
    # Procesar webhook basado en tipo de evento
    pass

if __name__ == '__main__':
    app.run(port=3000)

Usa hmac.compare_digest() en lugar de == para comparar firmas en Python. Esta función realiza una comparación segura contra ataques de tiempo que previene ataques de temporización.

Go (Gin)

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "io/ioutil"
    "log"
    "net/http"
    "os"

    "github.com/gin-gonic/gin"
)

type WebhookPayload struct {
    Event     string                 `json:"event"`
    Timestamp string                 `json:"timestamp"`
    Payload   map[string]interface{} `json:"payload"`
}

func main() {
    r := gin.Default()
    r.POST("/webhooks/gu1", handleWebhook)
    r.Run(":3000")
}

func handleWebhook(c *gin.Context) {
    // Leer cuerpo sin procesar para verificación de firmas
    rawBody, err := ioutil.ReadAll(c.Request.Body)
    if err != nil {
        c.JSON(500, gin.H{"error": "Failed to read body"})
        return
    }

    // Verificar firma
    signature := c.GetHeader("X-Webhook-Signature")
    webhookSecret := os.Getenv("GU1_WEBHOOK_SECRET")

    if !verifySignature(rawBody, signature, webhookSecret) {
        log.Println("Invalid webhook signature")
        c.JSON(401, gin.H{"error": "Invalid signature"})
        return
    }

    // Analizar payload
    var payload WebhookPayload
    if err := json.Unmarshal(rawBody, &payload); err != nil {
        c.JSON(400, gin.H{"error": "Invalid JSON"})
        return
    }

    log.Printf("Received webhook: %s", payload.Event)

    // Procesar webhook
    handleWebhookEvent(payload)

    c.JSON(200, gin.H{
        "success": true,
        "message": "Webhook received",
    })
}

func verifySignature(rawBody []byte, signature, secret string) bool {
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(rawBody)
    expectedSignature := hex.EncodeToString(mac.Sum(nil))

    return hmac.Equal([]byte(signature), []byte(expectedSignature))
}

func handleWebhookEvent(payload WebhookPayload) {
    // Procesar webhook basado en tipo de evento
}

Cuerpo Sin Procesar vs JSON Analizado

Un error común es verificar la firma usando el objeto JSON analizado en lugar del cuerpo de solicitud sin procesar. Esto siempre fallará porque el formato JSON puede diferir.

// INCORRECTO: Verificando cuerpo analizado
app.post('/webhooks', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  // Esto NO funcionará - JSON.stringify puede formatear diferente
  const body = JSON.stringify(req.body);
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  if (signature === expectedSignature) {
    // Siempre fallará
  }
});

// CORRECTO: Verificando cuerpo sin procesar
app.use(express.json({
  verify: (req, res, buf) => {
    req.rawBody = buf.toString('utf8');
  }
}));

app.post('/webhooks', (req, res) => {
  const signature = req.headers['x-webhook-signature'];

  // Esto funciona - usando cuerpo sin procesar
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(req.rawBody)
    .digest('hex');

  if (signature === expectedSignature) {
    // Firma verificada exitosamente
  }
});

Qué firma Gu1 (y qué no)

Gu1 calcula HMAC-SHA256(secret, raw_request_body) y envía el digest hexadecimal en X-Webhook-Signature.

Entra en la firma	No entra
Bytes exactos del body del POST HTTP (string JSON UTF-8)	`X-Webhook-Timestamp`, `X-Webhook-ID`, `X-Webhook-Event` ni ningún otro header
	Query params o path de la URL
	Campos que tu middleware agrega o quita después de leer el body

Usá una comparación timing-safe al validar la firma (por ejemplo crypto.timingSafeEqual en Node.js). Ver la sección de buenas prácticas más abajo.

Historial de webhooks en el dashboard

El monitor de webhooks muestra el payload para debugging y soporte. Esa vista no es el string byte-a-byte que se firmó al momento del envío. Pretty-print, copiar desde la UI o hacer JSON.stringify() sobre un objeto parseado puede generar un string distinto y hacer que un envío correcto parezca inválido. Para depurar un fallo, compará el header X-Webhook-Signature que recibió tu endpoint con el HMAC calculado sobre el raw body de ese mismo request HTTP. No re-verifiques solo con el JSON del dashboard.

Fallos intermitentes de firma

Si la verificación funciona en algunos eventos pero en otros devuelve 401 Invalid signature con el mismo secret y endpoint, las causas habituales son:

JSON parseado y re-serializado — JSON.stringify(req.body) después de express.json() (o equivalente) no reproduce de forma confiable los bytes del body de Gu1. Payloads distintos (orden de keys, forma anidada, formato numérico) pueden fallar solo a veces.
Middleware que muta el body — deduplicar arrays, quitar campos null, ordenar keys o normalizar strings antes de verificar cambia el input firmado.
Secret incorrecto — secret regenerado en el dashboard mientras en tu entorno quedó el valor viejo.
Header de firma ausente — si el webhook no tiene secret configurado, Gu1 puede omitir X-Webhook-Signature; tratar un header faltante como firma inválida es esperable.

La verificación de firma es opcional pero recomendada. Gu1 igual entrega webhooks si no verificás; el 401 lo devuelve tu servidor cuando tu lógica de verificación rechaza el request.

Patrones de Idempotencia

Los webhooks pueden entregarse más de una vez debido a problemas de red, timeouts o reintentos. Implementa idempotencia para asegurar que procesas cada webhook solo una vez.

Idempotencia Basada en Base de Datos

Almacena IDs de webhook procesados en tu base de datos:

Node.js

async function handleWebhook(webhook) {
  const webhookId = `${webhook.payload.entityId}_${webhook.event}_${webhook.timestamp}`;

  // Verificar si ya fue procesado
  const alreadyProcessed = await db.webhookLog.findUnique({
    where: { webhookId }
  });

  if (alreadyProcessed) {
    console.log('Webhook already processed, skipping');
    return; // Saltar duplicado
  }

  // Procesar webhook
  await processWebhookEvent(webhook);

  // Marcar como procesado
  await db.webhookLog.create({
    data: {
      webhookId,
      event: webhook.event,
      processedAt: new Date(),
      payload: webhook
    }
  });
}

Idempotencia Basada en Caché

Para webhooks de alto volumen, usa un caché como Redis:

Node.js con Redis

const Redis = require('ioredis');
const redis = new Redis();

async function handleWebhook(webhook) {
  const webhookId = `${webhook.payload.entityId}_${webhook.event}_${webhook.timestamp}`;

  // Intentar establecer la clave con NX (solo si no existe)
  const result = await redis.set(
    `webhook:${webhookId}`,
    '1',
    'EX', 86400, // Expira después de 24 horas
    'NX'
  );

  if (!result) {
    console.log('Webhook already processed, skipping');
    return; // Ya procesado
  }

  // Procesar webhook
  await processWebhookEvent(webhook);
}

Python con Redis

import redis
import json

redis_client = redis.Redis(host='localhost', port=6379, db=0)

def handle_webhook(webhook):
    webhook_id = f"{webhook['payload']['entityId']}_{webhook['event']}_{webhook['timestamp']}"

    # Intentar establecer la clave con NX (solo si no existe)
    result = redis_client.set(
        f"webhook:{webhook_id}",
        "1",
        ex=86400,  # Expira después de 24 horas
        nx=True
    )

    if not result:
        print('Webhook already processed, skipping')
        return  # Ya procesado

    # Procesar webhook
    process_webhook_event(webhook)

Mejores Prácticas de Seguridad

1. Siempre Verificar Firmas

Nunca omitas la verificación de firmas en ambientes de producción. Esta es tu defensa principal contra webhooks falsos.

// Siempre verificar la firma
if (!verifySignature(req.rawBody, signature, secret)) {
  return res.status(401).json({ error: 'Invalid signature' });
}

2. Usar Solo HTTPS

Configura tus endpoints de webhook para usar solo HTTPS. Rechaza solicitudes HTTP:

app.post('/webhooks', (req, res) => {
  // Verificar si la solicitud es HTTPS
  if (req.protocol !== 'https') {
    return res.status(403).json({ error: 'HTTPS required' });
  }

  // Procesar webhook...
});

3. Validar Tipos de Eventos

Solo procesa tipos de eventos que esperas:

const ALLOWED_EVENTS = [
  'entity.created',
  'entity.updated',
  'entity.status_changed',
  'kyc.validation_approved'
];

if (!ALLOWED_EVENTS.includes(webhook.event)) {
  console.warn('Unknown event type:', webhook.event);
  return res.status(400).json({ error: 'Unknown event type' });
}

4. Implementar Límite de Tasa

Protege tu endpoint del abuso con limitación de tasa:

const rateLimit = require('express-rate-limit');

const webhookLimiter = rateLimit({
  windowMs: 1 * 60 * 1000, // 1 minuto
  max: 100, // Limitar cada IP a 100 solicitudes por minuto
  message: 'Too many webhook requests'
});

app.post('/webhooks', webhookLimiter, handleWebhook);

5. Almacenar Secretos de Webhook de Forma Segura

Nunca hardcodees secretos de webhook. Usa variables de entorno o gestión de secretos:

// Bueno - variable de entorno
const secret = process.env.GU1_WEBHOOK_SECRET;

// Malo - hardcodeado
const secret = 'abc123'; // ¡Nunca hagas esto!

Para producción, usa un administrador de secretos:

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
Google Secret Manager

6. Validar Estructura del Payload

Valida la estructura del payload del webhook antes de procesar:

function isValidEntityPayload(payload) {
  return (
    payload &&
    payload.entity &&
    payload.entity.id &&
    payload.entity.type
  );
}

if (!isValidEntityPayload(webhook.payload)) {
  return res.status(400).json({ error: 'Invalid payload structure' });
}

7. Usar Comparaciones Seguras contra Tiempo

Al comparar firmas, usa funciones de comparación seguras contra tiempo para prevenir ataques de temporización:

const crypto = require('crypto');

function verifySignature(rawBody, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  // Comparación segura contra tiempo
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

8. Implementar Logs de Webhook

Registra todos los intentos de webhook para auditoría y depuración:

async function logWebhook(webhook, success, error = null) {
  await db.webhookLog.create({
    data: {
      event: webhook.event,
      timestamp: webhook.timestamp,
      success,
      error: error?.message,
      payload: webhook,
      processedAt: new Date()
    }
  });
}

9. Devolver 200 Rápidamente

Responde con código de estado 200 rápidamente para prevenir reintentos. Procesa trabajo pesado de forma asíncrona:

app.post('/webhooks', async (req, res) => {
  // Verificar firma primero
  if (!verifySignature(req.rawBody, signature, secret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Confirmar inmediatamente
  res.status(200).json({ received: true });

  // Procesar de forma asíncrona
  processWebhook(req.body).catch(console.error);
});

10. Implementar Lógica de Reintentos

Si falla el procesamiento del webhook, almacénalo para reintento:

try {
  await processWebhook(webhook);
} catch (error) {
  // Almacenar webhook fallido para reintento
  await db.failedWebhook.create({
    data: {
      webhook,
      error: error.message,
      retryCount: 0,
      nextRetryAt: new Date(Date.now() + 5 * 60 * 1000) // Reintentar en 5 minutos
    }
  });

  // Aún devolver 200 para prevenir que Gu1 reintente
  res.status(200).json({ success: false });
}

Errores Comunes de Seguridad a Evitar

Evita estos errores comunes de seguridad que pueden comprometer tus endpoints de webhook:

1. Omitir Verificación de Firmas

// NO HAGAS ESTO - Sin verificación de firmas
app.post('/webhooks', (req, res) => {
  // Procesando webhook sin verificación
  handleWebhook(req.body);
  res.status(200).send('OK');
});

Riesgo: Cualquiera puede enviar webhooks falsos a tu endpoint.

2. Verificar JSON Analizado en Lugar de Cuerpo Sin Procesar

// NO HAGAS ESTO - Verificando cuerpo analizado
app.post('/webhooks', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const body = JSON.stringify(req.body); // ¡Incorrecto!

  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  // Siempre fallará
});

Riesgo: La verificación de firmas siempre fallará.

3. Usar HTTP en Lugar de HTTPS

// NO HAGAS ESTO - Aceptando HTTP
http://tuapp.com/webhooks

Riesgo: Los payloads de webhook pueden ser interceptados en tránsito.

4. Hardcodear Secretos

// NO HAGAS ESTO - Secreto hardcodeado
const secret = 'my-webhook-secret-123';

Riesgo: Secretos expuestos en control de versiones o logs.

5. No Implementar Idempotencia

// NO HAGAS ESTO - Procesando duplicados
app.post('/webhooks', (req, res) => {
  // Sin verificación de duplicados
  await createUser(req.body.entity);
  res.status(200).send('OK');
});

Riesgo: Webhooks duplicados crearán registros duplicados.

6. Exponer Errores a Clientes

// NO HAGAS ESTO - Exponiendo errores internos
app.post('/webhooks', async (req, res) => {
  try {
    await processWebhook(req.body);
  } catch (error) {
    res.status(500).json({
      error: error.stack, // Exponiendo stack trace
      query: error.query  // Exponiendo consulta de base de datos
    });
  }
});

Riesgo: Fuga de información interna a atacantes.

7. No Validar Tipos de Eventos

// NO HAGAS ESTO - Procesando eventos desconocidos
app.post('/webhooks', (req, res) => {
  // Aceptando cualquier tipo de evento
  handleAnyEvent(req.body.event, req.body.payload);
});

Riesgo: Atacantes pueden enviar tipos de eventos arbitrarios.

8. Usar Secretos Débiles

// NO HAGAS ESTO - Secreto débil
const secret = '123456';

Riesgo: Los secretos pueden ser forzados por fuerza bruta. Solución: Usa secretos fuertes, generados aleatoriamente (al menos 32 caracteres).

Probar Seguridad de Webhook

Probar Firmas Inválidas

# Probar con firma inválida
curl -X POST https://tuapp.com/webhooks \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: invalid-signature" \
  -d '{"event":"entity.created","payload":{}}'

# Debería devolver 401 Unauthorized

Probar Ataques de Repetición

Envía el mismo webhook dos veces y verifica idempotencia:

# Enviar webhook una vez
curl -X POST https://tuapp.com/webhooks \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: valid-signature" \
  -d '{"event":"entity.created","timestamp":"2025-01-07T10:00:00Z","payload":{"entity":{"id":"123"}}}'

# Enviar mismo webhook de nuevo
curl -X POST https://tuapp.com/webhooks \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: valid-signature" \
  -d '{"event":"entity.created","timestamp":"2025-01-07T10:00:00Z","payload":{"entity":{"id":"123"}}}'

# Segunda solicitud debería ser ignorada (idempotencia)

Monitoreo y Alertas

Configura monitoreo para seguridad de webhook:

// Rastrear métricas de webhook
const metrics = {
  totalReceived: 0,
  signatureVerified: 0,
  signatureFailed: 0,
  processed: 0,
  failed: 0
};

app.post('/webhooks', (req, res) => {
  metrics.totalReceived++;

  const signature = req.headers['x-webhook-signature'];
  if (!verifySignature(req.rawBody, signature, secret)) {
    metrics.signatureFailed++;

    // Alertar si hay demasiados fallos de firma
    if (metrics.signatureFailed > 10) {
      alertSecurityTeam('High webhook signature failure rate');
    }

    return res.status(401).json({ error: 'Invalid signature' });
  }

  metrics.signatureVerified++;
  // Procesar webhook...
});

Próximos Pasos

Configuración de Webhook

Aprende cómo configurar webhooks

Eventos de Entidades

Maneja eventos de ciclo de vida de entidades

Eventos de KYC

Procesa eventos de verificación de KYC

Eventos de Reglas

Responde a reglas de cumplimiento

​Descripción General

​Verificación de Firmas

​Cómo Funciona la Verificación de Firmas

​Ejemplos de Verificación de Firmas

​Node.js (Express)

​Python (Flask)

​Go (Gin)

​Cuerpo Sin Procesar vs JSON Analizado

​Qué firma Gu1 (y qué no)

​Historial de webhooks en el dashboard

​Fallos intermitentes de firma

​Patrones de Idempotencia

​Idempotencia Basada en Base de Datos

​Idempotencia Basada en Caché

​Mejores Prácticas de Seguridad

​Errores Comunes de Seguridad a Evitar

​1. Omitir Verificación de Firmas

​2. Verificar JSON Analizado en Lugar de Cuerpo Sin Procesar

​3. Usar HTTP en Lugar de HTTPS

​4. Hardcodear Secretos

​5. No Implementar Idempotencia

​6. Exponer Errores a Clientes

​7. No Validar Tipos de Eventos

​8. Usar Secretos Débiles

​Probar Seguridad de Webhook

​Probar Firmas Inválidas

​Probar Ataques de Repetición

​Monitoreo y Alertas

​Próximos Pasos

Configuración de Webhook

Eventos de Entidades

Eventos de KYC

Eventos de Reglas

Descripción General

Verificación de Firmas

Cómo Funciona la Verificación de Firmas

Ejemplos de Verificación de Firmas

Node.js (Express)

Python (Flask)

Go (Gin)

Cuerpo Sin Procesar vs JSON Analizado

Qué firma Gu1 (y qué no)

Historial de webhooks en el dashboard

Fallos intermitentes de firma

Patrones de Idempotencia

Idempotencia Basada en Base de Datos

Idempotencia Basada en Caché

Mejores Prácticas de Seguridad

Errores Comunes de Seguridad a Evitar

1. Omitir Verificación de Firmas

2. Verificar JSON Analizado en Lugar de Cuerpo Sin Procesar

3. Usar HTTP en Lugar de HTTPS

4. Hardcodear Secretos

5. No Implementar Idempotencia

6. Exponer Errores a Clientes

7. No Validar Tipos de Eventos

8. Usar Secretos Débiles

Probar Seguridad de Webhook

Probar Firmas Inválidas

Probar Ataques de Repetición

Monitoreo y Alertas

Próximos Pasos