Configurar webhooks
Registrar un destino, guardar su secreto, activarlo y elegir los eventos que recibe tu sistema.
La API avisa a tu sistema cuando cambia un documento. Funciona en simulación y habilitación, y requiere que el operador haya configurado el proceso de webhooks y su clave de cifrado.
El aviso es mínimo: indica qué documento cambió. Consulta GET /v1/documents/{resource_id} para conocer el estado actual. Los archivos pueden terminar de generarse después del aviso fiscal.
Eventos
| Evento | Cuándo |
|---|---|
document.admitted | Se admitió el documento. |
document.validated | La DIAN (o la simulación) lo validó. |
document.rejected | Fue rechazado. |
document.action_required | Necesita intervención. |
document.cancelled | Se canceló. |
Otros valores del enum EventType del contrato aún no se producen y se rechazan al suscribir. Los destinos no reciben eventos anteriores a su creación o activación.
Registrar un destino
Crear inactivo con POST /v1/webhook-endpoints (permiso webhooks:write, Idempotency-Key):
{
"url": "https://tu-proyecto.example/webhooks/trifaco",
"event_types": ["document.validated", "document.rejected", "document.action_required", "document.cancelled"],
"active": false
}Guardar secret y key_id. Se entregan una sola vez. Repetir la creación devuelve 409 SECRET_ALREADY_DELIVERED sin el secreto. Si lo pierdes, rota el secreto.
Instalar el secreto en tu receptor y desplegarlo (ver Verificar y recibir).
Activar con PATCH /v1/webhook-endpoints/{id}, enviando todos los campos de entrada con active: true e If-Match igual al ETag de GET /v1/webhook-endpoints/{id}.
Implementación de referencia: backend/examples/webhook-register.ts.
Requisitos de la URL
- HTTPS público en el puerto 443.
- Sin credenciales en la URL, fragmentos,
localhost, IP privadas o especiales, ni traducciones IPv6. - No se siguen redirecciones.
- Se resuelve el DNS antes de cada intento y se fija una IP pública al conectar, conservando la validación TLS del nombre.
Máximo cinco destinos por empresa y ambiente. Para probar en tu equipo, usa un túnel (ver Recorrido local).
Consultar
GET /v1/webhook-endpointsyGET /v1/webhook-endpoints/{id}.GET /v1/webhook-events,GET /v1/webhook-events/{id}yGET /v1/webhook-events/{id}/attempts.
Los listados aceptan limit hasta 100 y cursor (paginación), requieren webhooks:read y solo muestran tu empresa y ambiente.