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, para que no tengas que preguntar en un bucle.
Los destinos se registran por la API, con cualquiera de tus claves, o desde el panel en Webhooks: ahí también ves cada aviso enviado con lo que respondió tu servidor y puedes reenviarlo.
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, con su Idempotency-Key:
{
"url": "https://tu-proyecto.example/webhooks/cufy",
"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}.
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 necesitas una URL pública con HTTPS: un túnel como cloudflared o ngrok sirve.
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), y solo muestran tu empresa y ambiente.