# Endpoints (/en/docs/webhooks)

Webhooks are the intended integration. A document takes anywhere from 30 seconds to several hours to
reach a terminal state at the SII (Chile's tax authority); listening is cheaper and faster than asking.

## Register an endpoint [#register-an-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"
}
```

> **Trap — The secret is returned exactly once**
>
> `whsec_…` appears in the creation response and never again. Store it wherever you store your other
> credentials. If you lose it, `POST /v1/webhook_endpoints/{webhook_endpoint_id}/rotate_secret` gives
> you a new one — and the old one keeps signing for 24 hours so you can deploy without a gap.

* `enabled_events: ["*"]` subscribes you to everything, including event types added later.
* `empresas` defaults to every empresa the key can see.
* Test-mode keys create test-mode endpoints, which only receive test-mode events.

## Manage [#manage]

```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"
```

## The payload [#the-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` is the full current resource — the same JSON a `GET` would return. For the four
`empresa.onboarding.*` events that resource is always the complete onboarding body (the same
object `GET .../onboarding` returns), never a sub-object — a mandato, a go-live authorization, a
certification set file. When what triggered the event is narrower than the full resource, that
smaller fact rides separately, in `data.detail` (`empresa.onboarding.step.completed` uses it to
say `{ "step": "mandato" }`).

`previous_attributes` shows up on updates and carries only what changed — what the field USED TO
BE, while `detail` is a different object entirely.

- [Verify the signature](/en/docs/webhooks/firma): HMAC-SHA256 over the raw bytes, with code you can copy.

- [Delivery and retries](/en/docs/webhooks/entrega): The retry schedule, the auto-disable, and the 12-month replay.

- [Event catalogue](/en/docs/webhooks/eventos): Every type, grouped by what happened in the world.