Saltar al contenido

Integraciones

Webhooks

Los webhooks te avisan cuando algo cambia, sin que tengas que consultar la API: una conexión nueva, movimientos nuevos o un problema con las credenciales. Enviamos un POST con JSON a tu URL, firmado con HMAC-SHA256.

Configurar

Hay dos formas de recibir eventos, y puedes usar ambas:

  • Endpoints registrados. En el panel, en Webhooks, agrega una URL, elige el modo (live o test) y los eventos que quieres recibir. Cada endpoint tiene su propio secreto de firma (whsec_…), que puedes ver en el panel. Desde ahí también puedes enviar un evento de prueba y revisar las entregas.
  • URL por conexión. Si creas el link token con webhook_url, esa URL recibe todos los eventos de esa conexión. Se firman con el secreto de webhooks de links de tu organización y modo, que también muestra el panel.

La URL debe ser HTTPS, pública (no localhost ni redes privadas) y usar el puerto 443 u 8443. Los eventos de un modo solo van a endpoints del mismo modo.

Eventos

typeCuándodata
link.createdUna persona terminó el widget y la conexión quedó creada, con su primera lectura.{ link }
link.refreshedTerminó una sincronización exitosa (automática o pedida con refresh).{ link }
movements.newUna sincronización o la conexión inicial encontró movimientos nuevos.{ link_id, account_ids, new_movements }
link.credentials_invalidEl banco rechazó la clave guardada. La conexión deja de sincronizarse.{ link }
link.action_requiredEl banco pide una acción a la persona. La conexión deja de sincronizarse.{ link }
link.deletedLa conexión fue revocada por API o desde el panel.{ link }

El botón Enviar prueba del panel envía un link.refreshed con data igual a { test: true, message }, firmado como cualquier otro evento.

Payload

Todos los eventos tienen la misma forma:

idstring
Id único del evento (evt_…). Se repite en los reintentos: úsalo para no procesar dos veces.
objectstring
Siempre event.
typestring
Tipo de evento.
modestring
Modo de la conexión.livetest
created_atstring (date-time)
Cuándo ocurrió.
dataobject
Contenido según el tipo.
{
  "id": "evt_5b1f0c9e7a2d4c8b3e6f1a09",
  "object": "event",
  "type": "link.created",
  "mode": "test",
  "created_at": "2026-11-18T14:02:12.006Z",
  "data": {
    "link": {
      "id": "link_9f2c41ab7e05d318",
      "object": "link",
      "institution": {
        "id": "sandbox",
        "name": "Banco de Prueba"
      },
      "holder_type": "business",
      "holder_name": "Panadería La Espiga SpA",
      "holder_id": "76123874-4",
      "status": "active",
      "status_message": null,
      "mode": "test",
      "allow_mcp": true,
      "last_refreshed_at": "2026-11-18T14:02:11.482Z",
      "next_refresh_at": "2026-11-19T14:02:11.482Z",
      "created_at": "2026-11-18T14:02:09.917Z"
    }
  }
}

movements.new no incluye los movimientos: trae la cantidad de movimientos nuevos y las cuentas del link. Léelos con GET /v1/accounts/{id}/movements.

Cada solicitud lleva estos encabezados:

EncabezadoValor
Content-Typeapplication/json
Banky-Signaturet=<unix>,v1=<hex>: marca de tiempo y firma.
Banky-Event-IdEl id del evento.
User-AgentBanky-Webhooks/1.0 (+https://banky.cl/docs)

Verificar la firma

Verifica siempre la firma antes de confiar en un evento. El encabezado Banky-Signature tiene la forma t=1763474532,v1=5f2c…. Para verificarlo:

  1. Separa t (segundos Unix) y la firma v1. Puede haber más de un v1: basta con que uno coincida.
  2. Calcula HMAC-SHA256 de <t>.<cuerpo crudo> usando como clave el secreto completo, incluido el prefijo whsec_, y pásalo a hexadecimal.
  3. Compara en tiempo constante con la firma recibida.
  4. Rechaza el evento si t se aleja más de 5 minutos de tu hora actual: así evitas que alguien reenvíe un evento antiguo.
import crypto from "node:crypto";
import express from "express";

const app = express();

// Usa el cuerpo crudo: la firma se calcula sobre los bytes exactos que enviamos.
app.post("/webhooks/banco", express.raw({ type: "application/json" }), (req, res) => {
  const cuerpo = req.body.toString("utf8");
  const firma = req.get("Banky-Signature");
  if (!verificarFirma(cuerpo, firma, process.env.BANKY_WEBHOOK_SECRET)) {
    return res.status(400).send("Firma inválida");
  }

  const evento = JSON.parse(cuerpo);
  // Responde rápido y procesa en segundo plano (cola, job, etc.).
  encolar(evento);
  res.sendStatus(200);
});

function verificarFirma(cuerpo, encabezado, secreto, toleranciaSegundos = 300) {
  if (!encabezado) return false;
  const partes = encabezado.split(",").map((p) => p.trim().split("="));
  const t = Number(partes.find(([clave]) => clave === "t")?.[1]);
  const firmas = partes.filter(([clave]) => clave === "v1").map(([, valor]) => valor);
  if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranciaSegundos) return false;

  const esperada = crypto.createHmac("sha256", secreto).update(`${t}.${cuerpo}`).digest();
  return firmas.some((firma) => {
    const recibida = Buffer.from(firma, "hex");
    return recibida.length === esperada.length && crypto.timingSafeEqual(recibida, esperada);
  });
}

Reintentos

Una entrega es exitosa si tu servidor responde con un código 2xx en menos de 10 segundos. No seguimos redirecciones: un 3xx cuenta como fallo.

IntentoCuándo
1De inmediato.
2 y 31 y 4 segundos después del anterior.
45 minutos después.
530 minutos después.
62 horas después.
76 horas después.
812 horas después. Es el último intento.

Si la URL resuelve a una red privada, no reintentamos. Cada intento queda registrado en el panel, con el código HTTP y el error.

Buenas prácticas

  • Responde 2xx lo antes posible y procesa el evento en segundo plano.
  • Haz el procesamiento idempotente con el id del evento: por los reintentos, puedes recibir el mismo evento más de una vez.
  • No dependas del orden de llegada. Si necesitas el estado actual, consulta el link con GET /v1/links/{id}.
  • Guarda el secreto de firma como variable de entorno, igual que la llave de API.