Webhooks en AccBooks AI

¿Qué son los webhooks?

Los webhooks son llamadas HTTP que AccBooks envía a tu servidor cuando se producen eventos específicos. En lugar de consultar la API periódicamente para comprobar cambios, registras una URL y AccBooks te envía los datos del evento en tiempo real.

Ejemplo de flujo:

1. Un cliente paga una factura en AccBooks.
2. AccBooks envía inmediatamente una solicitud POST a tu URL de webhook.
3. Tu sistema recibe el evento invoice.paid y activa tu flujo de trabajo de tramitación.

Configurar un webhook

1. Ve a Configuración → Integraciones → API → Webhooks → Añadir webhook.
2. Introduce tu URL de endpoint — la URL HTTPS en tu servidor que recibirá los eventos.
3. Selecciona los eventos que quieres recibir (ver lista más abajo).
4. Haz clic en Guardar.
5. AccBooks envía un evento de prueba a tu URL para verificar que es accesible.

Tu endpoint debe devolver un estado HTTP 2xx en 10 segundos. Si no lo hace, AccBooks reintenta hasta 5 veces con retroceso exponencial (1s, 2s, 4s, 8s, 16s).

Eventos disponibles

Evento	Se activa cuando
transaction.created	Se importa una nueva transacción bancaria
transaction.classified	Se clasifica una transacción (manual o por IA)
invoice.created	Se crea una nueva factura
invoice.sent	Se envía una factura por correo al cliente
invoice.paid	Una factura está íntegramente pagada
invoice.overdue	Una factura supera su fecha de vencimiento sin pagar
payroll.run_finalised	Se finaliza una ejecución de nóminas
vat.return_filed	Se presenta una declaración de IVA ante HMRC
bank_feed.error	Un feed bancario se desconecta o falla
bank_feed.synced	Un feed bancario sincroniza nuevos datos con éxito
company.year_end_closed	Se completa el proceso de cierre de ejercicio

Formato del payload del webhook

Todos los webhooks envían un payload JSON:

{
  "id": "evt_01HXYZ123",
  "type": "invoice.paid",
  "created_at": "2026-04-15T14:32:00Z",
  "data": {
    "invoice_id": "inv_0123",
    "customer_id": "cust_456",
    "amount": 2500.00,
    "currency": "GBP",
    "paid_at": "2026-04-15T14:31:55Z"
  }
}

Verificar la autenticidad del webhook

AccBooks firma cada solicitud de webhook con un secreto compartido (HMAC-SHA256). Verifica la firma antes de procesar el evento:

import hmac
import hashlib

def verify_signature(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode('utf-8'),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# En tu manejador de webhook:
signature = request.headers.get('AccBooks-Signature')
is_valid = verify_signature(request.body, signature, tu_secreto_webhook)

El secreto compartido se muestra cuando creas el webhook en AccBooks.

Gestionar eventos duplicados

Los problemas de red pueden ocasionalmente hacer que AccBooks envíe el mismo evento dos veces. Cada evento tiene un id único: guarda los IDs de eventos procesados y comprueba si hay duplicados antes de procesar.

Registros de webhooks

Ve a Configuración → Integraciones → API → Webhooks → [tu endpoint] → Registros para ver:

• Todos los eventos enviados en los últimos 7 días.
• El código de estado HTTP devuelto por tu servidor.
• Tiempo de respuesta.
• Cualquier fallo de entrega y reintentos.

Los eventos fallidos pueden reintentarse manualmente desde la página de registros.

Desactivar y reactivar

Activa o desactiva el interruptor Activo en cualquier webhook para desactivarlo temporalmente sin eliminar la configuración. Útil durante ventanas de mantenimiento en tu servidor.