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.
previous_attributes aparece en las actualizaciones y trae solo lo que cambió.
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.