Saltar al contenido principal

Webhooks

Endpoints para recibir eventos en tiempo real desde Manteca y Bridge, con validación de firma, manejo de reintentos y buenas prácticas de seguridad.

🔔 Eventos en tiempo real

Los webhooks notifican cambios críticos (KYC, órdenes, depósitos, customers, cuentas virtuales). Deben procesarse rápidamente, validar firma y ser idempotentes.

1) Webhook de Manteca​

POST/webhook

Recibe eventos de webhook enviados por Manteca

📤 Respuesta

{
"success": true,
"message": "Evento procesado exitosamente"
}

Headers:

Content-Type: application/json
X-Manteca-Signature: <signature>

Body – ejemplo (DOCUMENT_VALIDATION):

{
  "event": "DOCUMENT_VALIDATION",
  "data": {
    "numberId": "12345",
    "userExternalId": "swp_98808656",
    "document": "DNI_FRONT",
    "validated": true,
    "comment": "Documento válido",
    "date": "2024-01-15T10:30:00Z",
    "newLimit": 50000,
    "newLimitMonth": 10000
  }
}

2) Webhook de Bridge​

POST/bridge/webhook

Recibe eventos de webhook enviados por Bridge

📤 Respuesta

{
"success": true,
"message": "Evento procesado exitosamente"
}

Headers:

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

Body – ejemplo (customer.updated):

{
  "event_category": "customer",
  "event_type": "customer.updated",
  "event_object_id": "bridge_customer_123",
  "event_object": {
    "id": "bridge_customer_123",
    "status": "active",
    "email": "user@example.com"
  }
}

🔔 Eventos de Manteca​

DOCUMENT_VALIDATION

Notifica cambios en el estado de validación KYC.

{
  "event": "DOCUMENT_VALIDATION",
  "data": {
    "numberId": "12345",
    "userExternalId": "swp_98808656",
    "document": "DNI_FRONT",
    "validated": true,
    "newLimit": 50000
  }
}

ORDER_COMPLETED

Notifica cuando una orden fue completada.

{
  "event": "ORDER_COMPLETED",
  "data": {
    "numberId": "67890",
    "coin": "DAI_ARS",
    "operation": "BUY",
    "amount": "100.00",
    "price": "1250.75"
  }
}

FIAT_DEPOSIT

Notifica depósitos fiat acreditados.

{
  "event": "FIAT_DEPOSIT",
  "data": {
    "depositId": "dep_123",
    "amount": "5000.00",
    "currency": "ARS",
    "status": "COMPLETED"
  }
}

🔵 Eventos de Bridge​

customer.created / verified

Eventos del ciclo de vida del customer (creación, verificación KYC).

virtual_account.credited

Notifica cuando se acreditan fondos en una cuenta virtual.

🔒 Verificación de Seguridad​

Firma de Manteca

const crypto = require('crypto');

function verifyMantecaWebhook(payload, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return signature === computed;
}

Firma de Bridge

function verifyBridgeWebhook(payload, signature, timestamp, secret) {
  const signedPayload = `${timestamp}.${payload}`;
  const computed = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return signature === `sha256=${computed}`;
}

🔄 Manejo de Errores y Reintentos​

Política de reintentos

  • Manteca: 3 intentos (backoff exponencial)
  • Bridge: 5 intentos (backoff exponencial)
  • Timeout: 30s por intento
// OK → no reintenta
res.status(200).json({ success: true });

// Error temporal → reintenta
res.status(500).json({ error: "Temporary failure" });

// Error permanente → no reintenta
res.status(400).json({ error: "Invalid payload" });

📊 Logging y Monitoreo​

Estructura de log recomendada

{
  "timestamp": "2024-01-15T10:30:00Z",
  "webhook_type": "bridge",
  "event": "customer.verified",
  "processing_time_ms": 150,
  "status": "success"
}

Métricas clave

  • Latencia promedio < 200ms
  • Tasa de éxito > 99%
  • Reintentos < 1%

⚠️ Errores Comunes​

Problemas frecuentes

  • Firma inválida
  • Payload malformado
  • Eventos duplicados (falta de idempotencia)
  • Timeouts por procesamiento lento

📝 Notas Importantes​

Buenas prácticas

  • Implementar idempotencia por event_object_id
  • Validar siempre firma y timestamp
  • Responder rápido (< 30s)
  • Registrar todos los eventos para auditoría
  • Configurar alertas si fallos > 5%