# Endpoints (/docs/webhooks)

Los webhooks son la integración prevista. Un documento tarda entre 30 segundos y varias horas en
llegar a un estado terminal en el SII; escuchar es más barato y más rápido que preguntar.

## Registrar un endpoint [#registrar-un-endpoint]

```bash
curl -sS https://api.facturia.cl/v1/webhook_endpoints \
  -H "Authorization: Bearer $FACTURIA_KEY" -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.miempresa.cl/hooks/facturia",
    "description": "Producción — pipeline de facturación",
    "enabled_events": ["document.accepted","document.rejected","document.reparo","received_document.created"],
    "empresas": ["77928532-4"]
  }'
```

```json
{
  "id": "whe_01K2RF5N8Q2W",
  "object": "webhook_endpoint",
  "mode": "live",
  "url": "https://api.miempresa.cl/hooks/facturia",
  "enabled_events": ["document.accepted","document.rejected","document.reparo","received_document.created"],
  "empresas": ["77928532-4"],
  "secret": "whsec_9Kd2mQ7xR4vN8pL1tY6bZ3wA5cE0uJhF",
  "status": "enabled",
  "created_at": "2026-08-14T14:40:00Z"
}
```

> **Trampa — El secreto se devuelve una sola vez**
>
> `whsec_…` aparece en la respuesta de creación y nunca más. Guárdalo donde guardas tus otras
> credenciales. Si lo pierdes, `POST /v1/webhook_endpoints/{webhook_endpoint_id}/rotate_secret` te da
> uno nuevo — y el anterior sigue firmando 24 horas para que puedas desplegar sin corte.

* `enabled_events: ["*"]` te suscribe a todo, incluidos los tipos de evento futuros.
* `empresas` por defecto son todas las que la llave puede ver.
* Las llaves de modo test crean endpoints de modo test, que solo reciben eventos de modo test.

## Administrar [#administrar]

```bash
curl https://api.facturia.cl/v1/webhook_endpoints -H "Authorization: Bearer $FACTURIA_KEY"

curl -X PATCH https://api.facturia.cl/v1/webhook_endpoints/whe_01K2RF5N8Q2W \
  -H "Authorization: Bearer $FACTURIA_KEY" -H "Content-Type: application/json" \
  -d '{"enabled_events":["*"]}'

curl -X DELETE https://api.facturia.cl/v1/webhook_endpoints/whe_01K2RF5N8Q2W \
  -H "Authorization: Bearer $FACTURIA_KEY"

# Enviar un evento sintético para verificar la plomería
curl -X POST https://api.facturia.cl/v1/webhook_endpoints/whe_01K2RF5N8Q2W/ping \
  -H "Authorization: Bearer $FACTURIA_KEY"

# Rotar el secreto; el anterior sigue funcionando 24 h
curl -X POST https://api.facturia.cl/v1/webhook_endpoints/whe_01K2RF5N8Q2W/rotate_secret \
  -H "Authorization: Bearer $FACTURIA_KEY"
```

## El payload [#el-payload]

```http
POST /hooks/facturia HTTP/1.1
Content-Type: application/json
Facturia-Signature: t=1755180415,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
Facturia-Event-Id: evt_01K2RG1P4M7X
Facturia-Delivery-Id: whd_01K2RG1P4M7X01
Facturia-Delivery-Attempt: 1
```

```json
{
  "id": "evt_01K2RG1P4M7X",
  "object": "event",
  "type": "document.accepted",
  "api_version": "v1",
  "mode": "live",
  "created_at": "2026-08-14T13:06:55Z",
  "empresa": { "id": "emp_01K2R6ZC4P8QW1VN7T3MHDY9EK", "rut": "77928532-4" },
  "data": {
    "object": { "id": "doc_01K2R7Q4XW9M3B8ZC5YHTVJD6N", "object": "document", "status": "accepted", "…": "…" },
    "previous_attributes": { "status": "sent" }
  }
}
```

`data.object` es el recurso actual completo — el mismo JSON que devolvería un `GET`. Para los
cuatro eventos `empresa.onboarding.*` ese recurso es siempre la puesta en marcha completa (el
mismo objeto que devuelve `GET .../onboarding`), nunca un sub-objeto — un mandato, una
autorización de puesta en vivo, un archivo del set de certificación. Cuando lo que disparó el
evento es más específico que el recurso completo, ese hecho más chico viaja aparte, en
`data.detail` (`empresa.onboarding.step.completed` lo usa para decir `{ "step": "mandato" }`).

`previous_attributes` aparece en las actualizaciones y trae solo lo que cambió — es lo que el
campo ERA antes, mientras que `detail` es un objeto distinto.

- [Verificar la firma](/docs/webhooks/firma): HMAC-SHA256 sobre los bytes crudos, con código que puedes copiar.

- [Entrega y reintentos](/docs/webhooks/entrega): El calendario de reintentos, el auto-apagado y el replay de 12 meses.

- [Catálogo de eventos](/docs/webhooks/eventos): Todos los tipos, agrupados por lo que le pasó al mundo.