Kuenta Docs

Appearance

Webhooks ​

Los webhooks te permiten que Kuenta notifique a tu sistema, mediante una solicitud HTTP saliente, cuando ocurre un evento sobre un crédito de una línea de crédito (credit line) específica.

A diferencia de un modelo de suscripción a eventos genéricos, en Kuenta un webhook es una configuración (URL, cuerpo, autenticación) que se asocia a una línea de crédito y se dispara en dos puntos concretos del ciclo de vida del crédito.

Eventos que disparan un webhook ​

Hoy existen dos puntos de disparo, ambos configurados en la línea de crédito:

  • onOrderWebhooks: se dispara cuando se aprueba un pago (orden) sobre una cuota del crédito.
  • onDeliveredWebhooks: se dispara cuando el crédito pasa a estado Desembolsado.

No existe un catálogo abierto de eventos arbitrarios (por ejemplo, creación de una solicitud, firma de un documento, o carga de un documento de perfil). Si tu integración necesita notificarse en un momento distinto a estos dos, contacta a soporte técnico para evaluar agregar un nuevo punto de disparo.

Configuración de un webhook ​

1. Crear un webhook ​

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

{
  "tag": "notificacion-desembolso",
  "url": "https://tu-dominio.com/webhook",
  "requestHeader": "{\"Content-Type\":\"application/json\"}",
  "requestBody": "{\"creditId\":\"{{ .Credit.ID }}\",\"status\":\"{{ .Credit.Status }}\"}",
  "authEnabled": false
}

Campos disponibles al crear/actualizar un webhook:

CampoDescripción
tagIdentificador corto del webhook, útil para distinguirlo en los logs.
urlURL de destino a la que Kuenta enviará la solicitud POST.
requestHeaderEncabezados HTTP a enviar (JSON), admite la misma sintaxis de plantilla que requestBody.
requestBodyCuerpo de la solicitud. Es una plantilla (ver más abajo).
authEnabledSi true, Kuenta obtiene un token antes de cada envío (ver "Autenticación saliente").
authUrl, authMethod, authRequestBody, authRequestHeaderConfiguración de la solicitud previa para obtener el token.
tokenSourceKey, tokenType, authHeader, tokenHeaderDónde extraer el token de esa respuesta y cómo inyectarlo en la petición del webhook.
responseQueriesMapa de expresiones JSONPath para extraer valores de la respuesta de tu endpoint y guardarlos, disponibles luego para otras plantillas mediante fromWebhook.

2. Listar webhooks ​

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

3. Obtener un webhook ​

http
GET /v1/webhook/{webhookid}
Organization-ID: tu-id-de-organizacion

4. Actualizar un webhook ​

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

{
  "url": "https://tu-nuevo-dominio.com/webhook",
  "requestBody": "{\"creditId\":\"{{ .Credit.ID }}\"}"
}

5. Eliminar (archivar) un webhook ​

http
DELETE /v1/webhook/{webhookid}
Organization-ID: tu-id-de-organizacion

6. Probar un webhook ​

Ejecuta el envío inmediatamente con un crédito vacío (sin necesidad de tener un crédito real ni de asociarlo a una línea de crédito) y devuelve el detalle completo de la solicitud/respuesta, útil mientras se configura la plantilla:

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

{
  "url": "https://tu-dominio.com/webhook",
  "requestBody": "{\"ping\":true}"
}

7. Ejecutar manualmente un webhook para un crédito existente ​

http
POST /v1/webhook/{webhookid}/request
Content-Type: application/json
Organization-ID: tu-id-de-organizacion

{
  "creditID": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "logID": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}

Vincular el webhook a una línea de crédito ​

Crear un webhook por sí solo no hace que se dispare — debe asociarse a la línea de crédito (credit line) correspondiente, en el campo onOrderWebhooks (pago aprobado) o onDeliveredWebhooks (crédito desembolsado). Esta asociación se configura al editar la línea de crédito, no en el propio webhook. Contacta a soporte técnico o a tu equipo de implementación para configurar esta asociación.

Cuerpo de la solicitud (requestBody) ​

El campo requestBody (y requestHeader) es una plantilla (sintaxis de text/template de Go, con funciones adicionales tipo Sprig) que se evalúa en el momento del envío contra el crédito que disparó el webhook. Puedes referenciar cualquier campo del crédito y de su deudor, por ejemplo:

{{ .Credit.ID }}
{{ .Credit.Status }}
{{ .Credit.Debtor.Natural.FirstName }}
{{ .Credit.Debtor.Natural.WorkCertificateFileID }}

Importante: la plantilla puede incluir identificadores (por ejemplo, el ID de un documento del perfil), pero no el contenido binario ni el Base64 del archivo. Para obtener el archivo, tu sistema debe llamar aparte a:

http
GET /v1/debtor/{debtorId}/profile/{campo}/{fileId}
Authorization: Bearer <access_token>

que devuelve el archivo directamente (binario, sin envoltorio JSON ni Base64), autenticado con el mismo token Bearer de tu cliente OAuth.

Autenticación saliente (hacia tu endpoint) ​

Si tu endpoint requiere autenticación, Kuenta puede obtener un token antes de cada envío:

  • authEnabled: true + authUrl + authMethod + authRequestBody + authRequestHeader: Kuenta hace una solicitud previa a esa URL para obtener un token.
  • tokenSourceKey + tokenType + authHeader: dónde extraer el token de esa respuesta (del cuerpo o de un header, según tokenHeader) y en qué header inyectarlo en la petición del webhook.

Nota: Kuenta no agrega una firma HMAC ni un secreto compartido a cada solicitud del webhook. Si necesitas verificar el origen de la petición, acuerda con tu equipo de implementación un encabezado estático (vía requestHeader) que valides de tu lado.

Diagnóstico ​

Cada envío queda registrado, con la solicitud y la respuesta completas, asociado al crédito que lo disparó. Si un envío falla o tu integración no está recibiendo lo esperado, comparte el tag del webhook y el ID del crédito con soporte técnico para revisar el registro.

Kuenta no reintenta automáticamente un envío fallido (endpoint caído, timeout, respuesta de error, etc.). Si necesitas reenviar una notificación puntual, puede ejecutarse manualmente con POST /v1/webhook/{webhookid}/request (ver arriba). Para integraciones críticas, considera usar la API para consultar el estado del crédito como respaldo en caso de que un envío se pierda.

Próximos pasos ​

Soporte ​

Si necesitas ayuda con la configuración de webhooks: