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
| type | Cuándo | data |
|---|---|---|
link.created | Una persona terminó el widget y la conexión quedó creada, con su primera lectura. | { link } |
link.refreshed | Terminó una sincronización exitosa (automática o pedida con refresh). | { link } |
movements.new | Una sincronización o la conexión inicial encontró movimientos nuevos. | { link_id, account_ids, new_movements } |
link.credentials_invalid | El banco rechazó la clave guardada. La conexión deja de sincronizarse. | { link } |
link.action_required | El banco pide una acción a la persona. La conexión deja de sincronizarse. | { link } |
link.deleted | La 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:
| Encabezado | Valor |
|---|---|
Content-Type | application/json |
Banky-Signature | t=<unix>,v1=<hex>: marca de tiempo y firma. |
Banky-Event-Id | El id del evento. |
User-Agent | Banky-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:
- Separa
t(segundos Unix) y la firmav1. Puede haber más de unv1: basta con que uno coincida. - Calcula HMAC-SHA256 de
<t>.<cuerpo crudo>usando como clave el secreto completo, incluido el prefijowhsec_, y pásalo a hexadecimal. - Compara en tiempo constante con la firma recibida.
- Rechaza el evento si
tse 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.
| Intento | Cuándo |
|---|---|
| 1 | De inmediato. |
| 2 y 3 | 1 y 4 segundos después del anterior. |
| 4 | 5 minutos después. |
| 5 | 30 minutos después. |
| 6 | 2 horas después. |
| 7 | 6 horas después. |
| 8 | 12 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
iddel 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.