import { Aside } from "@astrojs/starlight/components";

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](/webhooks/catalogo-de-eventos/).

## Crear una suscripción

```
POST /api/v1/webhooks
```

```json
{
  "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](/webhooks/verificar-firma/) de cada entrega:

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

<Aside type="caution" title="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.
</Aside>

## 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](/webhooks/entrega-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:

```json
{ "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.