Isaak puede enviar eventos POST a tu URL cuando algo cambia: factura emitida, validación AEAT, certificado a punto de caducar. La beta de webhooks está abierta caso por caso — pide acceso a soporte@verifactu.business.
Todos los eventos comparten la misma envoltura. El campo type identifica el evento y data contiene el snapshot relevante.
{
"id": "evt_2026_05_27_abc123",
"type": "invoice.issued",
"createdAt": "2026-05-27T10:23:45.000Z",
"tenantId": "tnt_xxx",
"data": {
"invoiceId": "inv_2026_0042",
"number": "2026/0042",
"amount": 1210.00,
"verifactuHash": "a1b2c3d4...",
"aeatStatus": "registered"
}
}Cada petición incluye un header X-Isaak-Signature con HMAC-SHA256 del cuerpo crudo concatenado con el timestamp. Verifica siempre la firma antes de confiar en el payload.
// Verificación de firma HMAC (Node.js)
import crypto from 'node:crypto';
function verifyWebhook(req, secret) {
const signature = req.headers['x-isaak-signature'];
const timestamp = req.headers['x-isaak-timestamp'];
const body = req.rawBody; // ¡el cuerpo crudo, NO parseado!
// Rechazar si la firma tiene más de 5 minutos (anti-replay)
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
throw new Error('Timestamp fuera de ventana');
}
const payload = `${timestamp}.${body}`;
const expected = crypto
.createHmac('sha256', secret)
.update(payload)
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
throw new Error('Firma inválida');
}
}Selecciona los eventos a los que quieres suscribirte al crear el endpoint. Los scopes de la API key que firma el webhook controlan qué eventos puedes recibir.
| Evento | Disparador | Scope requerido |
|---|---|---|
invoice.draft.created | Un borrador de factura ha sido creado (vía API, MCP o dashboard). | isaak.invoices.read |
invoice.issued | Factura emitida y registrada con éxito en AEAT (VeriFactu). | isaak.invoices.read |
invoice.rejected | AEAT rechazó el registro. El campo `data.reason` indica el motivo. | isaak.invoices.read |
invoice.cancelled | Factura rectificativa emitida sobre una previa. | isaak.invoices.read |
verifactu.status.changed | Cambio en el estado de comunicación con AEAT (alta, baja, mantenimiento). | isaak.verifactu.read |
certificate.expiring | Certificado mTLS a 30, 15 o 7 días de caducar. Aviso recurrente hasta renovar. | isaak.company.read |
banking.transaction.matched | Una transacción bancaria se ha conciliado automáticamente con una factura. | isaak.fiscal.read |
api_key.created | Nueva API key creada en el tenant. Útil para auditoría. | isaak.audit.read |
api_key.revoked | API key revocada (manual o por rotación automática). | isaak.audit.read |
id para deduplicar.createdAt, no en el orden de recepción.