Skip to main content

Bridge - Utilidades

Endpoints auxiliares para configuración y monitoreo de Bridge.

1. Obtener Webhooks de Bridge​

GET /bridge/webhooks

Obtiene la configuración de webhooks de Bridge.

Headers:

Authorization: Bearer <JWT_TOKEN>

Respuesta Exitosa (200):

{
  "success": true,
  "data": {
    "webhooks": [
      {
        "id": "wh_123",
        "url": "https://swapbits.site/api/bank/bridge/webhook",
        "event_categories": ["customer", "virtual_account"],
        "status": "active"
      }
    ]
  },
  "message": "Webhooks de Bridge obtenidos exitosamente"
}

🔧 Configuración de Webhooks​

Eventos Soportados​

Customer Events​

  • customer.created - Customer creado
  • customer.updated - Customer actualizado
  • customer.verified - Customer verificado
  • customer.rejected - Customer rechazado

Virtual Account Events​

  • virtual_account.created - Cuenta virtual creada
  • virtual_account.credited - Fondos recibidos
  • virtual_account.debited - Fondos enviados

External Account Events​

  • external_account.created - Cuenta externa creada
  • external_account.updated - Cuenta externa actualizada

📋 Estructura de Webhook​

Headers​

Content-Type: application/json
X-Bridge-Signature: <signature>
X-Bridge-Timestamp: <timestamp>

Body Base​

{
  "event_category": "customer",
  "event_type": "customer.updated",
  "event_object_id": "bridge_customer_123",
  "event_object": {
    // Objeto específico del evento
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

🔒 Verificación de Webhooks​

Validación de Signature​

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === `sha256=${computedSignature}`;
}

Headers de Seguridad​

  • X-Bridge-Signature: Firma HMAC SHA-256
  • X-Bridge-Timestamp: Timestamp Unix
  • User-Agent: Bridge-Webhooks/1.0

📊 Monitoreo y Logs​

Estados de Webhook​

  • active - Funcionando correctamente
  • inactive - Desactivado temporalmente
  • failed - Múltiples fallos consecutivos
  • paused - Pausado manualmente

Reintentos​

  • Máximo: 5 intentos
  • Intervalo: Exponencial (1s, 2s, 4s, 8s, 16s)
  • Timeout: 30 segundos por intento

🛠️ Configuración de Desarrollo​

URLs de Webhook​

  • Producción: https://api.swapbits.com/bank/bridge/webhook
  • Staging: https://staging-api.swapbits.com/bank/bridge/webhook
  • Desarrollo: https://ngrok.io/your-tunnel/bridge/webhook

Testing con ngrok​

# Instalar ngrok
npm install -g ngrok

# Exponer puerto local
ngrok http 3000

# URL resultante
https://abc123.ngrok.io/bridge/webhook

🔍 Debugging​

Logs de Webhook​

{
  "webhook_id": "wh_123",
  "event_type": "customer.updated",
  "delivery_id": "del_456",
  "status": "delivered",
  "response_code": 200,
  "response_time_ms": 150,
  "attempts": 1,
  "timestamp": "2024-01-15T10:30:00Z"
}

Códigos de Estado​

  • 200-299: Éxito (no se reintenta)
  • 300-399: Redirección (se reintenta)
  • 400-499: Error cliente (no se reintenta)
  • 500-599: Error servidor (se reintenta)

📈 Métricas​

Disponibilidad​

  • Target: 99.9% uptime
  • SLA: Respuesta < 30s
  • Monitoring: 24/7

Volumetría​

  • Rate Limit: 1000 webhooks/min
  • Batch Size: 1 evento por webhook
  • Retention: 30 días de logs

⚠️ Errores Comunes​

Webhook Failures​

  • Timeout: Endpoint no responde en 30s
  • Invalid Response: Código HTTP no 2xx
  • Connection Error: DNS/Red no disponible
  • SSL Error: Certificado inválido

Debugging Steps​

  1. Verificar URL del webhook
  2. Validar certificado SSL
  3. Comprobar firewall/rate limiting
  4. Revisar logs del servidor
  5. Validar formato de respuesta

📝 Notas Importantes​

  • Los webhooks son la forma principal de recibir actualizaciones en tiempo real
  • Siempre validar la firma para seguridad
  • Implementar idempotencia para manejar duplicados
  • Responder rápidamente (< 30s) para evitar reintentos
  • Usar HTTPS siempre en producción