Se emite al crear una nueva orden de venta.
Lista de eventos
Se emite cuando una orden cambia de datos o estado.
Se emite cuando la orden es cancelada.
Se emite cuando la orden queda finalizada.
Se emite al terminar la post-emision de un CFE.
Se emite cuando se registra un CFE recibido.
Cambio de estado de contrato por reglas de uso.
Primeros pasos
Registro de endpoint para integradores: POST /api/v1/webhooks.
Configura tu URL de recepcion, define eventos suscritos y usa el payload JSON para procesar cambios de forma automatica.
Alta de endpoint
Endpoint: POST /api/v1/webhooks
Campos requeridos: url, events.
Parametro de query: idEmpresa (si no existe empresa en sesion).
secret se recomienda para habilitar firma HMAC en la entrega.
Ejemplo minimo
curl -X POST "$BASE_URL/api/v1/webhooks?idEmpresa=123" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
"url": "https://integrador.com/webhooks/bluetech",
"events": ["Cfe.Emitido"]
}'Ejemplo completo
curl -X POST "$BASE_URL/api/v1/webhooks?idEmpresa=123" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
"name": "ERP Produccion",
"url": "https://integrador.com/webhooks/bluetech",
"enabled": true,
"secret": "tu_clave_hmac",
"headers": {
"X-Integrador": "erp-central"
},
"events": [
"OrdenDeVenta.Creada",
"OrdenDeVenta.Finalizada",
"Cfe.Emitido"
]
}'Respuesta esperada (201)
{
"id": 845,
"url": "https://integrador.com/webhooks/bluetech",
"events": [
"OrdenDeVenta.Creada",
"OrdenDeVenta.Finalizada",
"Cfe.Emitido"
],
"enabled": true
}Errores frecuentes (400)
{
"error": "Campos requeridos: url, events."
}{
"error": "Payload vacío o inválido."
}Confirmacion y reintentos
Un webhook se toma como entregado cuando tu endpoint responde cualquier codigo 2xx (por ejemplo 200, 202 o 204).
Regla de entrega
2xx -> entregado (sin reintento)
429 -> reintenta
5xx -> reintenta
4xx -> no reintenta (se toma como fallo permanente)
timeout / error de red -> reintentaVentana de reintentos
Demoras progresivas:
5s, 60s, 120s, 300s, 600s, 1800s, 3600s, 7200s, 21600s
El maximo de intentos depende de la configuracion del endpoint.
En alta por API, el valor por defecto es 8 intentos.
Si se agotan los intentos, el evento queda como agotado.Recomendacion para integradores
1) Validar firma HMAC y estructura JSON.
2) Encolar procesamiento interno.
3) Responder 2xx rapido.
4) Procesar de forma idempotente usando Idempotency-Key.Personalizacion
Cuando publiquemos nuevos eventos o cambios de contrato, se anunciaran en Changelog para que puedas adaptar tu integracion.