Saltar al contenido principal

Bridge - Utilidades

Endpoints auxiliares para configuración y monitoreo de Bridge, con foco en webhooks (configuración, verificación de firma, reintentos y debugging).

🧰 Endpoints auxiliares de Bridge

Estos endpoints no forman parte del flujo principal de onboarding, pero son claves para operar en producción: inspección de webhooks, validación de seguridad y mejores prácticas de observabilidad.

1) Obtener Webhooks de Bridge​

GET/bridge/webhooks

Obtiene la configuración de webhooks de Bridge

📤 Respuesta

{
"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"
}

Headers:

Authorization: Bearer <JWT_TOKEN>

🔧 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 (HMAC SHA-256)

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 (referencia)

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

📊 Monitoreo y Logs​

Estados del 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 sugeridas por ambiente

  • 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​

Ejemplo de log de delivery

{
  "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 y reintentos

  • 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​

Objetivos y volumetría

  • Disponibilidad target: 99.9%
  • SLA: Respuesta < 30s
  • Monitoring: 24/7
  • Rate limit: 1000 webhooks/min
  • Retention: 30 días de logs

⚠️ Errores Comunes​

Webhook failures

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

Checklist de debugging

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

📝 Notas Importantes​

Buenas prácticas

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