EasyBankData.

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.

{
    "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

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

7. Seguridad y límites