Webhooks - Guía Profunda

const express = require('express');
const crypto = require('crypto');
 
const app = express();
 
// IMPORTANTE: Usar express.raw para verificación de firma
app.post('/webhooks/koywe',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    try {
      // 1. Verificar firma
      const signature = req.headers['koywe-signature'];
      const secret = process.env.KOYWE_WEBHOOK_SECRET;
      
      if (!verifyWebhookSignature(req.body, signature, secret)) {
        console.error('Firma de webhook inválida');
        return res.status(401).send('Firma inválida');
      }
      
      // 2. Parsear evento
      const event = JSON.parse(req.body.toString());
      
      // 3. Procesar evento
      await processWebhookEvent(event);
      
      // 4. Responder rápido
      res.status(200).send('OK');
      
    } catch (error) {
      console.error('Error procesando webhook:', error);
      res.status(500).send('Error interno');
    }
  }
);
 
function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === expectedSignature;
}
 
async function processWebhookEvent(event) {
  console.log('Evento recibido:', event.type);
  
  switch (event.type) {
    case 'order.completed':
      await handleOrderCompleted(event.data);
      break;
    case 'order.failed':
      await handleOrderFailed(event.data);
      break;
    // ... otros tipos de evento
  }
}

from flask import Flask, request
import hmac
import hashlib
import json
 
app = Flask(__name__)
 
@app.route('/webhooks/koywe', methods=['POST'])
def webhook():
    try:
        # 1. Verificar firma
        signature = request.headers.get('koywe-signature')
        secret = os.getenv('KOYWE_WEBHOOK_SECRET')
        
        if not verify_webhook_signature(request.data, signature, secret):
            return 'Firma inválida', 401
        
        # 2. Parsear evento
        event = json.loads(request.data)
        
        # 3. Procesar evento
        process_webhook_event(event)
        
        # 4. Responder rápido
        return 'OK', 200
        
    except Exception as e:
        print(f"Error procesando webhook: {e}")
        return 'Error interno', 500
 
def verify_webhook_signature(payload, signature, secret):
    expected_signature = hmac.new(
        secret.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()
    
    return signature == expected_signature

policy.{resourceType}.executed

{
  "id": "evt_abc123",
  "type": "order.completed",
  "version": "v1",
  "occurred_at": "2025-11-13T15:30:00Z",
  "source": "koywe.api",
  "environment": "production",
  "organization_id": "org_xyz",
  "merchant_id": "mrc_abc",
  "data": {
    "orderId": "ord_123456",
    "type": "PAYIN",
    "status": "COMPLETED",
    "amountIn": 50000,
    "amountOut": 50000,
    "originCurrencySymbol": "COP",
    "destinationCurrencySymbol": "COP",
    "externalId": "order-12345",
    "createdAt": "2025-11-13T15:00:00Z",
    "completedAt": "2025-11-13T15:30:00Z"
  }
}

const redis = require('redis');
const client = redis.createClient();
 
async function processWebhookEvent(event) {
  const eventId = event.id;
  
  // Verificar si ya procesamos este evento
  const alreadyProcessed = await client.get(`webhook:${eventId}`);
  
  if (alreadyProcessed) {
    console.log('Evento ya procesado, saltando');
    return;
  }
  
  // Procesar evento
  await handleEvent(event);
  
  // Marcar como procesado (expirar después de 7 días)
  await client.setEx(`webhook:${eventId}`, 604800, 'processed');
}

async function processWebhookEvent(event) {
  const eventId = event.id;
  
  // Insertar con constraint único
  try {
    await db.query(
      'INSERT INTO processed_webhooks (event_id, processed_at) VALUES ($1, NOW())',
      [eventId]
    );
  } catch (error) {
    if (error.code === '23505') { // Violación de constraint único
      console.log('Evento ya procesado');
      return;
    }
    throw error;
  }
  
  // Procesar evento
  await handleEvent(event);
}

const Bull = require('bull');
const webhookQueue = new Bull('webhooks');
 
// Endpoint de webhook - responde rápido
app.post('/webhooks/koywe', express.raw({type: 'application/json'}), async (req, res) => {
  // Convertir body raw a string una vez
  const rawBody = req.body.toString();
  
  if (!verifySignature(rawBody, req.headers['koywe-signature'])) {
    return res.status(401).send('Inválido');
  }
  
  // Parsear JSON desde string
  const event = JSON.parse(rawBody);
  
  // Agregar a cola y responder inmediatamente
  await webhookQueue.add(event);
  res.status(200).send('OK');
});
 
// Procesador de trabajos - maneja eventos en background
webhookQueue.process(async (job) => {
  const event = job.data;
  await processWebhookEvent(event);
});

async function logWebhookEvent(event, status, error = null) {
  await db.query(`
    INSERT INTO webhook_log (
      event_id, event_type, status, error, received_at
    ) VALUES ($1, $2, $3, $4, NOW())
  `, [event.id, event.type, status, error]);
}
 
app.post('/webhooks/koywe', async (req, res) => {
  const event = JSON.parse(req.body);
  
  try {
    await processWebhookEvent(event);
    await logWebhookEvent(event, 'success');
    res.status(200).send('OK');
  } catch (error) {
    await logWebhookEvent(event, 'error', error.message);
    res.status(500).send('Error');
  }
});

const processedEvents = new Set();
 
async function processWebhookEvent(event) {
  // Método en memoria simple (usar DB/Redis en producción)
  if (processedEvents.has(event.id)) {
    console.log('Evento duplicado, saltando');
    return;
  }
  
  processedEvents.add(event.id);
  await handleEvent(event);
}