Suscribirse

NovaFE avisa por webhook cada evento relevante de tu cuenta: cambios de estado de un comprobante, certificados o secuencias por vencer, cambios de contingencia, y más. Ver el catálogo completo.

Crear una suscripción

POST /api/v1/webhooks

{
  "url": "https://tu-erp.example.com/webhooks/novafe",
  "events": ["ecf.accepted", "ecf.rejected", "certificate.*"],
  "description": "Notificaciones a mi ERP"
}

Campo	Nota
url	HTTPS obligatorio fuera de desarrollo. Debe ser una URL absoluta.
events	Hasta 20 entradas. Acepta tipos exactos, comodín por categoría (ecf.*) o el comodín total (*).
description	Opcional, para identificar el endpoint en tu propio listado.

La respuesta trae el secret que vas a necesitar para verificar la firma de cada entrega:

{
  "endpoint": {
    "id": "...",
    "url": "...",
    "events": ["ecf.accepted", "ecf.rejected", "certificate.*"],
    "enabled": true
  },
  "secret": "whsec_..."
}

El secret se muestra una sola vez

Ni GET /webhooks ni GET /webhooks/{id} vuelven a devolverlo. Si lo pierdes, rota uno nuevo con POST /webhooks/{id}/rotate-secret: el anterior deja de servir de inmediato.

Por qué una URL privada no funciona

Antes de aceptar la URL (y de nuevo, en cada entrega), NovaFE verifica que no resuelva a una dirección privada: nada de localhost, redes internas (10.x, 172.16.x, 192.168.x), ni la dirección de metadata de la nube. Es una protección contra que un endpoint mal configurado, o uno malicioso, use tus webhooks para acceder a servicios internos que no debería poder alcanzar. Tu URL tiene que ser alcanzable públicamente por HTTPS.

Puedes tener hasta 5 endpoints por tenant.

Otras operaciones

GET    /api/v1/webhooks               listar (sin el secret)
GET    /api/v1/webhooks/{id}          uno puntual (sin el secret)
PATCH  /api/v1/webhooks/{id}          actualizar url, events, description o enabled
DELETE /api/v1/webhooks/{id}          eliminar

PATCH con { "enabled": false } pausa las entregas sin borrar la suscripción; es también la forma de reactivar un endpoint que NovaFE deshabilitó solo por fallar demasiado (ver Entrega y reintentos).

Probar un endpoint

POST /api/v1/webhooks/{id}/ping

Entrega un evento webhook.ping de prueba de inmediato, sin pasar por la cola de reintentos, y te devuelve el resultado en la misma respuesta:

{ "delivered": true, "statusCode": 200, "error": null }

Úsalo justo después de crear un endpoint, para confirmar que tu servidor lo recibe y responde antes de depender de él en producción.