Kuenta Docs

Appearance

Webhooks ​

Los webhooks te permiten recibir notificaciones en tiempo real sobre eventos importantes en tu cuenta de Kuenta.

Configuración de webhooks ​

1. Crear un webhook ​

http
POST /v1/webhooks
Content-Type: application/json
Config-Organization-ID: tu-id-de-organizacion
Organization-ID: tu-id-de-organizacion

{
  "url": "https://tu-dominio.com/webhook",
  "events": [
    "credit.application.created",
    "credit.application.approved",
    "credit.application.rejected",
    "payment.created",
    "payment.completed",
    "payment.failed"
  ],
  "secret": "tu-secreto-webhook"
}

2. Listar webhooks ​

http
GET /v1/webhooks
Config-Organization-ID: tu-id-de-organizacion
Organization-ID: tu-id-de-organizacion

3. Actualizar webhook ​

http
PUT /v1/webhooks/{id}
Content-Type: application/json
Config-Organization-ID: tu-id-de-organizacion
Organization-ID: tu-id-de-organizacion

{
  "url": "https://tu-nuevo-dominio.com/webhook",
  "events": ["payment.created", "payment.completed"]
}

4. Eliminar webhook ​

http
DELETE /v1/webhooks/{id}
Config-Organization-ID: tu-id-de-organizacion
Organization-ID: tu-id-de-organizacion

Eventos disponibles ​

Créditos ​

  • credit.application.created: Nueva solicitud de crédito
  • credit.application.approved: Solicitud aprobada
  • credit.application.rejected: Solicitud rechazada
  • credit.disbursed: Crédito desembolsado
  • credit.completed: Crédito completado

Pagos ​

  • payment.created: Nuevo pago creado
  • payment.completed: Pago completado
  • payment.failed: Pago fallido
  • payment.refunded: Pago reembolsado

Documentos ​

  • document.created: Documento creado
  • document.signed: Documento firmado
  • document.expired: Documento expirado

Validación ​

  • validation.started: Validación iniciada
  • validation.completed: Validación completada
  • validation.failed: Validación fallida

Estructura del payload ​

json
{
  "event": "credit.application.created",
  "data": {
    "id": "app_123",
    "amount": 5000000,
    "term": 12,
    "termUnit": "months",
    "status": "pending",
    "createdAt": "2024-03-20T10:00:00Z"
  },
  "timestamp": "2024-03-20T10:00:00Z"
}

Verificación de firmas ​

Python ​

python
import hmac
import hashlib

def verify_webhook_signature(payload, signature, secret):
    expected = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

Node.js ​

javascript
const crypto = require("crypto");

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Mejores prácticas ​

  1. Seguridad

    • Verifica siempre la firma del webhook
    • Usa HTTPS para tu endpoint
    • Implementa rate limiting
    • Almacena el secreto de forma segura

  2. Manejo de errores

    • Implementa reintentos con backoff exponencial
    • Registra los errores para debugging
    • Maneja timeouts apropiadamente

  3. Procesamiento

    • Procesa los webhooks de forma asíncrona
    • Responde rápidamente al webhook (200 OK)
    • Implementa idempotencia

Próximos pasos ​

Soporte ​

Si necesitas ayuda con la configuración de webhooks: