Endpoints
Registering an endpoint, what an event payload carries, and how to test the plumbing before you trust it.
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
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"]
}'{
"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.empresasdefaults to every empresa the key can see.- Test-mode keys create test-mode endpoints, which only receive test-mode events.
Manage
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
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{
"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.
Foreign digital services and tipo 46
The three-step cycle — enter the charge, read the suggestion, confirm — and where the charges come from if you don't have them.
Verify the signature
The format of the Facturia-Signature header, how the HMAC is computed, and the implementation mistake that voids the whole check.