Webhooks
Preguntar cada cinco minutos si hay algo nuevo es lo que hacen las integraciones que no quieren serlo. Registra un endpoint y te avisamos de lo que pasa: una lectura terminada, una cuenta nueva, una conexión que hay que volver a autorizar, una alerta… Cada aviso va firmado, se reintenta si tu servidor no contesta y queda en un historial donde ves lo que mandamos y lo que contestó. Ningún aviso lleva importes, saldos, cuentas, conceptos ni contrapartes: solo identificadores, recuentos y fechas. El detalle se pide a la API con tu clave.
1. Registrar un endpoint
En el panel, en API y webhooks › Webhooks › Nuevo endpoint, o por la API (lo que hace un módulo de
ERP al instalarse). Lo registra quien administra la empresa. Eliges los eventos sueltos, un grupo entero
con su comodín (alerta.*, que incluye lo que añadamos después a ese grupo) o
todos (*). Opcionalmente: una descripción, la versión del sobre, cabeceras
propias (por ejemplo la autorización de tu receptor, que se guarda cifrada y no se vuelve a enseñar) y
filtros por empresas y por cuentas. Una asesoría puede recibir en un solo endpoint los avisos de toda su
cartera: cada aviso dice de qué empresa es en tenant.
curl -X POST https://app.easybankdata.com/v1/tenants/{tenant}/webhooks \
-H "Authorization: Bearer ebd_live_…" -H "Content-Type: application/json" \
-d '{"name":"Módulo del ERP","url":"https://erp.example/easybankdata/webhook",
"events":["lectura.terminada","cuenta.nueva","alerta.*"],
"headers":{"Authorization":"Bearer mi-token-del-receptor"}}'
La respuesta trae el secreto (whsec_…) una sola vez: guárdalo, es con
lo que compruebas la firma. Después se gestiona todo por la API igual que en el panel:
PATCH y DELETE /webhooks/{webhook},
/disable y /enable,
/rotate_secret, /test,
/deliveries y /resend_failed. Con una clave de prueba el
endpoint es del sandbox: recibe solo los
avisos del sandbox y puede ser http://.
2. El sobre y sus versiones
Cada aviso es un POST con Content-Type: application/json.
El sobre depende de la versión que elegiste para el endpoint, y no cambia aunque salga otra: un receptor
que funciona no se rompe porque nosotros mejoremos el sobre.
2026-09-24:{id, type, occurred_at, tenant, data}, y"sandbox": trueen los del sandbox. Es la de los endpoints que ya existían.2026-10-19(la que propone el panel al crear; por la API, se pide conenvelope_version): ademásversionylivemodesiempre presente (falseen el sandbox).
{
"id": "evt_01jabcdxyzevento00000001",
"type": "cuenta.nueva",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001"
}
}
Un evento de prueba lleva además "test": true y datos de ejemplo. Las
cabeceras nuestras son tres: X-EasyBankData-Signature (la firma),
X-EasyBankData-Event (el id del evento, el mismo en cada
reintento y reenvío) y X-EasyBankData-Delivery (el de ese intento concreto).
3. Comprobar la firma
La cabecera es t=<segundos>,v1=<hmac>: v1 es
HMAC-SHA256, en hexadecimal, de <t>.<cuerpo> con tu secreto. La hora va
dentro de lo firmado, así que nadie puede cambiarla. Durante el plazo de gracia de una rotación llegan
dos v1: vale con que cuadre una. Tres reglas: el cuerpo crudo (si lo
vuelves a montar con tu librería el orden de las claves cambia y la firma deja de cuadrar), comparación en
tiempo constante y como mucho 120 segundos de diferencia con tu reloj.
PHP
$cuerpo = file_get_contents('php://input'); // crudo
$cabecera = $_SERVER['HTTP_X_EASYBANKDATA_SIGNATURE'] ?? '';
$t = null; $firmas = [];
foreach (explode(',', $cabecera) as $trozo) {
[$k, $v] = array_pad(explode('=', trim($trozo), 2), 2, '');
if ($k === 't') { $t = $v; }
if ($k === 'v1') { $firmas[] = $v; }
}
$mia = hash_hmac('sha256', $t.'.'.$cuerpo, $secreto);
$vale = ctype_digit((string) $t) && abs(time() - (int) $t) <= 120
&& array_filter($firmas, fn ($v1) => hash_equals($mia, $v1)) !== [];
if (! $vale) { http_response_code(401); exit; }
http_response_code(200); // y lo procesas después
Node.js
import crypto from 'node:crypto';
// `crudo` es el Buffer del cuerpo tal cual (express.raw({ type: 'application/json' }))
function esNuestro(crudo, cabecera, secreto) {
const partes = cabecera.split(',').map((p) => p.trim().split('='));
const t = partes.find(([k]) => k === 't')?.[1];
const firmas = partes.filter(([k]) => k === 'v1').map(([, v]) => v);
if (!/^\d+$/.test(t ?? '') || Math.abs(Date.now() / 1000 - Number(t)) > 120) return false;
const mia = crypto.createHmac('sha256', secreto).update(`${t}.`).update(crudo).digest('hex');
return firmas.some((v1) => v1.length === mia.length
&& crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(mia)));
}
Python
import hashlib, hmac, time
def es_nuestro(crudo: bytes, cabecera: str, secreto: str) -> bool:
partes = [p.strip().split('=', 1) for p in cabecera.split(',') if '=' in p]
t = next((v for k, v in partes if k == 't'), '')
firmas = [v for k, v in partes if k == 'v1']
if not t.isdigit() or abs(time.time() - int(t)) > 120:
return False
mia = hmac.new(secreto.encode(), t.encode() + b'.' + crudo, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(mia, v1) for v1 in firmas)
Descarta los repetidos por el id del evento: guárdalo al procesarlo y, si vuelve
a llegar (un reintento, un reenvío), contesta 200 sin hacer nada. Los avisos pueden llegar desordenados:
ordénalos por occurred_at.
4. Qué contestar, reintentos y desactivación
- Contesta 2xx en menos de 10 segundos en cuanto lo tengas, y procésalo después. Cualquier otra cosa (un 4xx, un 5xx, un 3xx —las redirecciones no se siguen—, o no contestar) es un intento fallido.
- Se reintenta cinco veces, esperando cada vez más (1 min, 5 min, 30 min, 2 h y 6 h, con un poco de azar): algo más de un día. El historial dice cuándo es el siguiente reintento.
- Un endpoint que pierde 10 avisos seguidos (cada uno con sus cinco intentos) se
desactiva solo, y se avisa por correo y en la campana del panel a quien lo creó. Se reactiva con
«Reanudar» (o
POST /webhooks/{webhook}/enable) cuando lo arregles. - En pausa o desactivado no recibe nada, pero lo que ocurre queda apuntado como
skipped: al reanudarlo, lo reenvías de una vez.
5. Rotar el secreto sin cortar
Rota el secreto si lo perdiste o se filtró. Sin plazo de gracia, el anterior deja de valer en el acto. Con un plazo de gracia (hasta 72 horas), cada aviso lleva las dos firmas —la del nuevo primero— y tu receptor sigue funcionando con cualquiera de los dos mientras cambias el suyo. El secreto nuevo se enseña una sola vez.
curl -X POST https://app.easybankdata.com/v1/tenants/{tenant}/webhooks/{webhook}/rotate_secret \
-H "Authorization: Bearer ebd_live_…" -H "Content-Type: application/json" \
-d '{"grace_period_hours":24}'
6. Probar, ver el historial y reenviar
- Enviar un evento de prueba: eliges cualquier evento del catálogo y lo mandamos en el acto, con
datos de ejemplo,
"test": truey la firma de verdad. Ves lo que contestó tu servidor. No cuenta para la salud del endpoint (POST …/test). - El historial: cada intento con su resultado, código, duración y siguiente reintento, filtrable
por resultado, evento y fechas. De cada entrega ves la petición (cabeceras —las tuyas, tapadas— y
cuerpo) y la respuesta recortada a 2 KB (
GET …/deliveries). El cuerpo se puede ver durante 30 días; el registro de intentos se guarda 90. - Reenviar: una entrega, o todas las que no llegaron en un periodo. Salen con el mismo
idy el mismo cuerpo, así que tu sistema reconoce y descarta lo que ya tenía (POST …/deliveries/{delivery}/resendyPOST …/resend_failed). - La salud: tasa de éxito, latencia (mediana y percentil 95), avisos perdidos seguidos y
reintentos pendientes de los últimos 7 días, en el panel y en
health.
7. Seguridad y límites
- La dirección tiene que ser HTTPS y resolver a una dirección pública: una de red privada, de bucle local o de metadatos de nube se rechaza al registrar y otra vez en cada entrega (los DNS cambian).
- No seguimos redirecciones, esperamos como mucho 5 segundos para conectar y 10 para la respuesta, y de la respuesta leemos 2 KB como mucho.
- Hasta 10 endpoints por empresa (los del sandbox, aparte) y 5 cabeceras propias por endpoint.
Las cabeceras del protocolo y las
X-EasyBankData-*no se pueden fijar. - Un endpoint registrado con una clave recibe solo lo que esa clave puede leer hoy (empresas, cuentas y el recurso de cada evento). Cada cambio (alta, edición, pausa, rotación, prueba, reenvío) queda en el registro de accesos de la empresa.
8. El catálogo de eventos
Lo mismo que da GET https://app.easybankdata.com/v1/webhooks/events. «El detalle» es el recurso de la
API que hay que poder leer para recibir el evento con un endpoint registrado por la API.
Lecturas lectura.*
lectura.terminada · Una lectura ha terminado y los datos ya están disponibles
Cuándo: Al terminar de importar una lectura que trajo datos.
Cuántas veces: Una por lectura.
Lleva:
connection_id, operation_id, accounts, transactions, read_at · El detalle: conexiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "lectura.terminada",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"connection_id": "01JABCDXYZCONEXION0000001",
"operation_id": "op_2f9c1d7e4b",
"accounts": 2,
"transactions": 37,
"read_at": "2026-10-19T08:30:00+00:00"
}
}
lectura.fallida · Una lectura ha fallado
Cuándo: Al terminar una lectura con un error del proveedor.
Cuántas veces: Una por lectura.
Lleva:
connection_id, operation_id, error_code · El detalle: conexiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "lectura.fallida",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"connection_id": "01JABCDXYZCONEXION0000001",
"operation_id": "op_2f9c1d7e4b",
"error_code": 2000
}
}
Conexiones conexion.*
conexion.necesita_autorizarse · Una conexión necesita que su usuario la autorice otra vez
Cuándo: Cuando una conexión pasa a necesitar autorización de nuevo.
Cuántas veces: Una por conexión y episodio: mientras siga necesitándolo no se repite.
Lleva:
connection_id · El detalle: conexiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "conexion.necesita_autorizarse",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"connection_id": "01JABCDXYZCONEXION0000001"
}
}
conexion.creada · Una conexión nueva ya tiene sus datos dentro
Cuándo: Cuando termina de importarse la primera lectura de una conexión que no existía (por la pantalla de tu banco, un enlace o la API). Sale además de `lectura.terminada`.
Cuántas veces: Una por conexión.
Lleva:
connection_id, operation_id · El detalle: conexiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "conexion.creada",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"connection_id": "01JABCDXYZCONEXION0000001",
"operation_id": "op_2f9c1d7e4b"
}
}
conexion.reautorizada · Una conexión que pedía autorización vuelve a leer
Cuándo: Cuando termina de importarse una lectura de una conexión que estaba en «necesita autorizarse»: el titular la ha vuelto a autorizar y se lee otra vez.
Cuántas veces: Una por episodio: la próxima, solo después de volver a necesitar autorización.
Lleva:
connection_id, operation_id · El detalle: conexiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "conexion.reautorizada",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"connection_id": "01JABCDXYZCONEXION0000001",
"operation_id": "op_2f9c1d7e4b"
}
}
Consentimientos consentimiento.*
consentimiento.proximo_a_caducar · El consentimiento de una conexión está a punto de caducar
Cuándo: Cuando a un consentimiento le quedan los días de aviso (30 por defecto).
Cuántas veces: Una por consentimiento y renovación.
Lleva:
connection_id, expires_at, days_left · El detalle: conexiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "consentimiento.proximo_a_caducar",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"connection_id": "01JABCDXYZCONEXION0000001",
"expires_at": "2026-10-19T08:30:00+00:00",
"days_left": 30
}
}
Enlaces de conexión sesion_de_conexion.*
sesion_de_conexion.abierta · El titular ha abierto un enlace de conexión y ha aceptado
Cuándo: Cuando el titular acepta en la página del enlace.
Cuántas veces: Una por sesión.
Lleva:
session_id, external_ref · El detalle: conexiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "sesion_de_conexion.abierta",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"session_id": "01JABCDXYZSESION000000001",
"external_ref": "cliente-1234"
}
}
sesion_de_conexion.completada · La conexión de un enlace se ha completado
Cuándo: Al importar la lectura de la conexión que abrió el enlace.
Cuántas veces: Una por sesión.
Lleva:
session_id, external_ref, connection_id, operation_id, reauthorization · El detalle: conexiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "sesion_de_conexion.completada",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"session_id": "01JABCDXYZSESION000000001",
"external_ref": "cliente-1234",
"connection_id": "01JABCDXYZCONEXION0000001",
"operation_id": "op_2f9c1d7e4b",
"reauthorization": false
}
}
sesion_de_conexion.fallida · La conexión de un enlace ha fallado
Cuándo: Cuando la lectura del enlace termina con un error del proveedor.
Cuántas veces: Una por sesión.
Lleva:
session_id, external_ref, operation_id, provider_error_code · El detalle: conexiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "sesion_de_conexion.fallida",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"session_id": "01JABCDXYZSESION000000001",
"external_ref": "cliente-1234",
"operation_id": "op_2f9c1d7e4b",
"provider_error_code": 2000
}
}
sesion_de_conexion.abandonada · Un enlace de conexión ha caducado sin terminar
Cuándo: Cuando el enlace caduca, o pasan 60 min tras aceptar sin abrir la pantalla de tu banco, o 24 h sin entrega.
Cuántas veces: Una por sesión.
Lleva:
session_id, external_ref, last_status · El detalle: conexiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "sesion_de_conexion.abandonada",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"session_id": "01JABCDXYZSESION000000001",
"external_ref": "cliente-1234",
"last_status": "authorizing"
}
}
Control de saldo saldo.*
saldo.descuadrado · El saldo de una cuenta no cuadra con sus movimientos
Cuándo: Cuando una cuenta falla dos comprobaciones de saldo seguidas (saldo de partida + movimientos distinto del saldo del banco).
Cuántas veces: Una por cuenta y episodio: mientras siga descuadrada no se repite.
Lleva:
account_id, connection_id, difference_cents · El detalle: cuentas
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "saldo.descuadrado",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"difference_cents": -1250
}
}
Traspasos entre tus cuentas traspasos.*
traspasos.por_revisar · Hay traspasos entre cuentas propias por revisar
Cuándo: Cuando una lectura o un extracto importado dejan traspasos entre cuentas propias propuestos sin revisar.
Cuántas veces: Una por lectura o extracto que los deje.
Lleva:
connection_id, count · El detalle: movimientos
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "traspasos.por_revisar",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"connection_id": "01JABCDXYZCONEXION0000001",
"count": 12
}
}
Extractos importados extracto.*
extracto.importado · Un extracto importado ya está dentro
Cuándo: Al terminar de volcar un extracto subido (panel o API), con los movimientos que entraron.
Cuántas veces: Una por extracto importado.
Lleva:
import_id, account_id, transactions · El detalle: movimientos
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "extracto.importado",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"import_id": "01JABCDXYZIMPORTACION0001",
"account_id": "01JABCDXYZCUENTA000000001",
"transactions": 37
}
}
Alertas de tesorería alerta.*
alerta.saldo_bajo · El saldo de una cuenta ha bajado del umbral fijado
Cuándo: Cuando una lectura deja el saldo por debajo del umbral de la cuenta y la anterior lo dejaba en el umbral o por encima.
Cuántas veces: Una por cruce del umbral; se rearma cuando una lectura lo deja otra vez en el umbral o por encima.
Lleva:
account_id, connection_id · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.saldo_bajo",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001"
}
}
alerta.cargo_grande · Ha entrado un cargo por encima del umbral de su cuenta
Cuándo: Cuando un movimiento nuevo de una lectura incremental supera, en valor absoluto, el umbral de su cuenta. La primera lectura de una conexión no lo dispara.
Cuántas veces: Una por movimiento.
Lleva:
account_id, connection_id, transaction_id · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.cargo_grande",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001"
}
}
alerta.recibo_devuelto · Posible recibo devuelto en una cuenta
Cuándo: Cuando un movimiento nuevo de una lectura incremental casa con un patrón declarado de devolución de recibo. La primera lectura no lo dispara.
Cuántas veces: Una por movimiento.
Lleva:
account_id, connection_id, transaction_id · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.recibo_devuelto",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001"
}
}
alerta.saldo_para_impuestos · El saldo previsto no llega para los impuestos de una fecha de cargo
Cuándo: Cuando el saldo previsto al final del día de un cargo de impuestos (303, 111, 115, 130 o 202) queda por debajo de cero, dentro de los 15 días anteriores al último día para domiciliarlo.
Cuántas veces: Una por empresa y fecha de cargo.
Lleva:
due_date, direct_debit_deadline, tax_models · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.saldo_para_impuestos",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"due_date": "2026-10-20",
"direct_debit_deadline": "2026-10-15",
"tax_models": [
"303",
"111"
]
}
}
alerta.recibo_nuevo · Hay un recibo o una suscripción nueva
Cuándo: Cuando una lectura incremental trae la tercera aparición, con un periodo semanal, mensual o trimestral, de un cargo que no se había visto antes en esa cuenta.
Cuántas veces: Una por recurrente.
Lleva:
alert_id, account_id, connection_id, transaction_id, recurrence_id · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.recibo_nuevo",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"alert_id": "01JABCDXYZALERTA000000001",
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001",
"recurrence_id": "01JABCDXYZRECURRENTE00001"
}
}
alerta.subida_de_precio · Un recibo de importe fijo ha subido
Cuándo: Cuando una lectura incremental trae un cargo recurrente que supera en más de un 1 % el importe de sus tres apariciones anteriores, que no variaban más de un 1 %.
Cuántas veces: Una por movimiento.
Lleva:
alert_id, account_id, connection_id, transaction_id, recurrence_id · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.subida_de_precio",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"alert_id": "01JABCDXYZALERTA000000001",
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001",
"recurrence_id": "01JABCDXYZRECURRENTE00001"
}
}
alerta.recibo_en_varias_cuentas · Un recibo pasa en varias cuentas o tarjetas
Cuándo: Cuando llega una aparición de un cargo recurrente que también pasa, al día y por un importe a no más de un 15 %, en otra cuenta o tarjeta. No se aplica a comisiones, impuestos, IVA, Seguridad Social, préstamos ni personal.
Cuántas veces: Una por recurrente y conjunto de cuentas.
Lleva:
alert_id, account_id, connection_id, transaction_id, recurrence_id · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.recibo_en_varias_cuentas",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"alert_id": "01JABCDXYZALERTA000000001",
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001",
"recurrence_id": "01JABCDXYZRECURRENTE00001"
}
}
alerta.recibo_no_ha_pasado · Un recibo de siempre no ha pasado
Cuándo: Tras leer una cuenta, cuando uno de sus cargos recurrentes lleva más de 5 días de retraso sobre su fecha esperada (y menos de un periodo).
Cuántas veces: Una por recurrente y fecha esperada.
Lleva:
alert_id, account_id, connection_id, transaction_id, recurrence_id · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.recibo_no_ha_pasado",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"alert_id": "01JABCDXYZALERTA000000001",
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001",
"recurrence_id": "01JABCDXYZRECURRENTE00001"
}
}
alerta.cobro_no_ha_llegado · Un cobro de siempre no ha llegado
Cuándo: Tras leer una cuenta, cuando una de sus entradas recurrentes lleva más de 5 días de retraso sobre su fecha esperada (y menos de un periodo).
Cuántas veces: Una por recurrente y fecha esperada.
Lleva:
alert_id, account_id, connection_id, transaction_id, recurrence_id · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.cobro_no_ha_llegado",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"alert_id": "01JABCDXYZALERTA000000001",
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001",
"recurrence_id": "01JABCDXYZRECURRENTE00001"
}
}
alerta.comision_nueva · El banco ha cobrado una comisión de un tipo nuevo
Cuándo: Cuando una lectura incremental trae una comisión de un tipo (mantenimiento, transferencia, tarjeta…) que la cuenta no ha tenido en los 13 meses anteriores, con al menos 90 días de histórico.
Cuántas veces: Una por movimiento.
Lleva:
alert_id, account_id, connection_id, transaction_id, recurrence_id · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.comision_nueva",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"alert_id": "01JABCDXYZALERTA000000001",
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001",
"recurrence_id": "01JABCDXYZRECURRENTE00001"
}
}
alerta.cargo_duplicado · Posible cargo duplicado
Cuándo: Cuando una lectura incremental trae un cargo con el mismo importe y concepto que otro de la misma cuenta a 3 días o menos, y en el histórico de esa cuenta ese concepto no se repite nunca tan seguido.
Cuántas veces: Una por movimiento.
Lleva:
alert_id, account_id, connection_id, transaction_id, recurrence_id · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.cargo_duplicado",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"alert_id": "01JABCDXYZALERTA000000001",
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001",
"recurrence_id": "01JABCDXYZRECURRENTE00001"
}
}
alerta.importe_inusual · Un movimiento está fuera de lo habitual
Cuándo: Cuando una lectura incremental trae un movimiento por encima del umbral propio de su concepto (8 movimientos o más) o de su categoría (20 o más): mediana y dispersión (MAD) del histórico de la empresa, 3,5 MAD y al menos el doble de la mediana.
Cuántas veces: Una por movimiento.
Lleva:
alert_id, account_id, connection_id, transaction_id, recurrence_id · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.importe_inusual",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"alert_id": "01JABCDXYZALERTA000000001",
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001",
"recurrence_id": "01JABCDXYZRECURRENTE00001"
}
}
alerta.presupuesto_casi_agotado · Un presupuesto ha llegado al 80 %
Cuándo: Tras una lectura, cuando lo real de un mes de un presupuesto de salidas (categoría del cliente o centro de coste; cuentas en euros, sin traspasos propios) llega al 80 % de lo presupuestado sin pasarlo, si el presupuesto tiene el aviso previo. Se mira el mes en curso y, los 5 primeros días, también el anterior.
Cuántas veces: Una por presupuesto y mes; tras «se ha pasado», el del 80 % ya no sale ese mes.
Lleva:
alert_id, budget_id, period · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.presupuesto_casi_agotado",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"alert_id": "01JABCDXYZALERTA000000001",
"budget_id": "01JABCDXYZPRESUPUESTO0001",
"period": "2026-10"
}
}
alerta.presupuesto_superado · Se ha pasado un presupuesto
Cuándo: Tras una lectura, cuando lo real de un mes de un presupuesto de salidas pasa de lo presupuestado (el 100 % justo no). Se mira el mes en curso y, los 5 primeros días, también el anterior.
Cuántas veces: Una por presupuesto y mes; tras «se ha pasado», el del 80 % ya no sale ese mes.
Lleva:
alert_id, budget_id, period · El detalle: tesoreria
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "alerta.presupuesto_superado",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"alert_id": "01JABCDXYZALERTA000000001",
"budget_id": "01JABCDXYZPRESUPUESTO0001",
"period": "2026-10"
}
}
Recibos devueltos recibo.*
recibo.devuelto · Un recibo devuelto (para el módulo del ERP que remesa)
Cuándo: Cuando entra un movimiento nuevo cuyo concepto casa con un patrón declarado de devolución de recibo, en una lectura incremental o en un extracto importado (lo posterior a lo que ya tenía la cuenta). La primera lectura y la importación que crea la cuenta no lo disparan. Lleva el movimiento original si se identifica sin dudas.
Cuántas veces: Una por movimiento devuelto: ni un reintento ni una lectura repetida la vuelven a mandar.
Lleva:
returned_receipt_id, account_id, connection_id, transaction_id, original_transaction_id, kind · El detalle: movimientos
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "recibo.devuelto",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"returned_receipt_id": "01JABCDXYZDEVOLUCION00001",
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001",
"original_transaction_id": "01JABCDXYZMOVIMIENTO00000",
"kind": "issued"
}
}
Peticiones de justificante justificante.*
justificante.pedido · Se ha pedido un justificante o una explicación de un movimiento
Cuándo: Cuando alguien del panel (o por la API) pide un justificante o una explicación de un movimiento, y cuando quien la pidió la reabre.
Cuántas veces: Una al pedir, y otra cada vez que quien la pidió la reabre.
Lleva:
request_id, transaction_id, account_id · El detalle: peticiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "justificante.pedido",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"request_id": "01JABCDXYZPETICION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001",
"account_id": "01JABCDXYZCUENTA000000001"
}
}
justificante.respondido · Una petición de justificante ha recibido respuesta
Cuándo: Cuando alguien con permiso responde una petición de justificante, con texto, con un adjunto o con los dos.
Cuántas veces: Una por respuesta.
Lleva:
request_id, transaction_id, account_id · El detalle: peticiones
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "justificante.respondido",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"request_id": "01JABCDXYZPETICION0000001",
"transaction_id": "01JABCDXYZMOVIMIENTO00001",
"account_id": "01JABCDXYZCUENTA000000001"
}
}
Cuentas cuenta.*
cuenta.nueva · Ha aparecido una cuenta o una tarjeta nueva
Cuándo: Cuando una lectura trae una cuenta o una tarjeta que esa conexión no había traído nunca (también en la primera lectura: una por cada cuenta).
Cuántas veces: Una por cuenta o tarjeta.
Lleva:
account_id, connection_id · El detalle: cuentas
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "cuenta.nueva",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001"
}
}
Movimientos movimientos.*
movimientos.nuevos · Una cuenta tiene movimientos nuevos
Cuándo: Al terminar de importar una lectura o un extracto, por cada cuenta que haya recibido movimientos que no estaban. No sale en las lecturas que no traen nada nuevo.
Cuántas veces: Una por cuenta y lectura (o extracto) con movimientos nuevos.
Lleva:
account_id, connection_id, count, origin · El detalle: movimientos
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "movimientos.nuevos",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"account_id": "01JABCDXYZCUENTA000000001",
"connection_id": "01JABCDXYZCONEXION0000001",
"count": 12,
"origin": "reading"
}
}
Plan plan.*
plan.cambiado · El plan de la suscripción ha cambiado
Cuándo: Cuando cambia el plan de la suscripción: una subida cobrada, una bajada o una cancelación que llegan a su fecha, o un cambio desde el soporte. El alta no lo dispara.
Cuántas veces: Una por cambio de plan.
Lleva:
plan, previous_plan · El detalle: facturacion
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "plan.cambiado",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"plan": "negocio",
"previous_plan": "esencial"
}
}
Cobros de la suscripción cobro.*
cobro.confirmado · Un cobro de la suscripción se ha confirmado
Cuándo: Cuando la pasarela confirma, con su respuesta firmada, un cobro del alta, de un periodo, de un prorrateo o de un cambio de tarjeta.
Cuántas veces: Una por cobro: un reintento es otro cobro.
Lleva:
payment_id, concept · El detalle: facturacion
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "cobro.confirmado",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"payment_id": "01JABCDXYZCOBRO0000000001",
"concept": "periodo"
}
}
cobro.fallido · Un cobro de la suscripción ha fallado
Cuándo: Cuando un cobro de la suscripción queda fallido: denegado por el banco, sin tarjeta o con la tarjeta caducada.
Cuántas veces: Una por cobro: un reintento es otro cobro.
Lleva:
payment_id, concept, reason · El detalle: facturacion
Ejemplo
{
"id": "evt_01jabcdxyzevento00000001",
"type": "cobro.fallido",
"version": "2026-10-19",
"occurred_at": "2026-10-19T08:30:00+00:00",
"tenant": "01JABCDXYZEMPRESA00000001",
"livemode": true,
"data": {
"payment_id": "01JABCDXYZCOBRO0000000001",
"concept": "periodo",
"reason": "denegada"
}
}