# Registrar webhook

`POST /api/v1/billing/webhooks`

Registra una URL HTTPS para recibir eventos vía webhook. Los eventos se
firman con HMAC-SHA256 usando el `secret` del webhook; el secret solo
se retorna completo al momento de crear el webhook.

> **Beta privada**: las escrituras vía API key están en beta privada
> (solicitar acceso: hola@simplo.cl); las API keys hoy operan en modo
> lectura.

- Autenticación: header `X-Api-Key: sk_simplo_...` (o `Authorization: Bearer <jwt>` para sesiones de la plataforma).
- operationId: `registrarWebhook` — contrato completo en https://docs.simplo.cl/openapi.yaml
- Versión HTML: https://docs.simplo.cl/api/operations/registrarwebhook/

## Request body (application/json)

Schema: `WebhookRequest`

| Campo | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `url` | string (uri) | sí | URL HTTPS donde se enviarán los eventos |
| `events` | string (dte.created \| dte.accepted \| dte.rejected \| dte.repaired \| caf.low_stock \| certificado.expiring)[] | sí | Eventos a los que suscribirse |
| `secret` | string | no | Secret para firma HMAC-SHA256 (se genera automáticamente si no se envía) |

## Ejemplo (curl)

```sh
curl -X POST "https://api.simplo.cl/api/v1/billing/webhooks" \
  -H "X-Api-Key: $SIMPLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://mi-app.cl/webhooks/simplo",
    "events": [
      "dte.created"
    ]
  }'
```

## Respuestas

### 201 — Webhook registrado

Schema: `WebhookResponse`

| Campo | Tipo | Requerido | Descripción |
| --- | --- | --- | --- |
| `id` | string (uuid) | sí |  |
| `url` | string (uri) | sí |  |
| `events` | string[] | sí |  |
| `secret` | string | no | Solo se retorna al crear el webhook. |
| `is_active` | boolean | sí |  |
| `created_at` | string (date-time) | sí |  |

### 400 — URL inválida o eventos no soportados

Schema: `ErrorResponse`

### 401 — Token o API key inválido o ausente

Schema: `ErrorResponse`