Endpoints
Registrar un endpoint, qué contiene el payload de un evento y cómo probar la plomería antes de confiar en ella.
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
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"
}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.empresaspor 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
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
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 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.
Servicios digitales extranjeros y el tipo 46
El ciclo de tres pasos — ingresar cargos, leer sugerencias, confirmar — y de dónde salen los cargos si no los tienes.
Verificar la firma
El formato del header Facturia-Signature, cómo se calcula el HMAC y el error de implementación que anula toda la verificación.