Solucionar fallos de entrega de webhooks
Los fallos de webhook significan que AtomicPay no pudo entregar un evento a tu endpoint, o tu endpoint lo rechazó. Esta guía se centra en entregas fallidas después de haber planificado la integración en planificar, probar y monitorear webhooks.
Úsala cuando los logs muestren fallos, cuando el simulador funcione pero producción no, o cuando tu sistema externo nunca reciba eventos que existen en Ventas.
Patrones de fallo
| Síntoma | Causa probable | Primer lugar a verificar |
|---|---|---|
| Los logs muestran entrega fallida | El endpoint devolvió error o expiró | Logs de webhook |
| El simulador funciona, producción falla | Payload, auth o entorno de producción difiere | Configuración del endpoint y logs |
| No se reciben eventos | URL incorrecta, webhook deshabilitado o eventos incorrectos seleccionados | Configuración de webhook |
| Acciones duplicadas en sistema externo | El endpoint no es idempotente en reintentos | Lógica de la aplicación receptora |
| Algunos eventos llegan, otros no | Selección de eventos o acción disparadora faltante | Eventos seleccionados y Ventas |
Flujo de investigación
- Abre el webhook en AtomicPay.
[Captura: Lista de webhooks — webhook objetivo abierto.]
- Confirma que la URL del endpoint es correcta y accesible públicamente.
[Captura: Configuración de webhook — URL del endpoint visible y válida.]
- Verifica qué eventos están seleccionados contra el flujo que esperas. Consulta planificación de webhooks.
[Captura: Eventos de webhook — eventos suscritos coinciden con el flujo.]
- Revisa logs de entrega para código de estado, intentos y marcas de tiempo.
[Captura: Logs de entrega de webhook — intentos fallidos con códigos de estado.]
- Ejecuta el simulador para el tipo de evento que falla.
[Captura: Simulador de webhook — evento de prueba enviado.]
- Compara éxito del simulador con el intento fallido de producción.
[Captura: Comparación de logs — éxito del simulador vs fallo de producción.]
- Corrige el endpoint externo para que devuelva una respuesta de éxito rápidamente.
[Captura: Endpoint externo — devuelve respuesta de éxito 2xx.]
- Dispara una venta de prueba real o evento de suscripción cuando sea seguro.
[Captura: Venta de prueba disparada — entrega de webhook reintentada.]
- Confirma que el sistema externo procesó el evento una vez, no múltiples veces.
[Captura: Sistema externo — evento único procesado, sin duplicados.]
- Si usas Zapier o Make, verifica la URL catch y el paso de automatización por separado.
[Captura: Zapier o Make — URL catch y paso de automatización verificados.]
Verificaciones del endpoint
| Verificación | Por qué importa |
|---|---|
Devolver 2xx rápidamente | Endpoints lentos causan reintentos y riesgo de duplicados. |
| Validar auth o firma | Consulta endpoints de webhook seguros. |
| Encolar trabajo pesado | No bloquees la respuesta HTTP en trabajos largos. |
| Hacer handlers idempotentes | Los reintentos no deben duplicar acceso o actualizaciones CRM. |
| Separar endpoints de prueba y producción | Previene que el éxito del simulador oculte errores de config de producción. |
Problemas comunes por tipo de evento
| Tipo de evento | También revisar |
|---|---|
| Compra aprobada | Acceso del comprador y flujo de entrega |
| Compra rechazada | Rechazos de tarjeta o fallos PIX |
| PIX generado | Pagos incompletos |
| Carrito abandonado | Flujo de recuperación |
| Reembolso o contracargo | Reembolsos y contracargos |
| Eventos de suscripción | Estado y timing de suscripciones |
Buenas prácticas
- Comienza con los eventos mínimos que tu automatización necesita.
- Prueba cada evento crítico de producción con el simulador antes del lanzamiento.
- Monitorea logs después de cambios en precios, producto o endpoint.
- Mantén referencia de payload en documentación de API.
- Documenta comportamiento de reintentos en tu lado antes de depender de webhooks para provisionar acceso.
Errores comunes
- Reconstruir el webhook sin corregir el endpoint.
- Apuntar webhooks de producción a una URL solo local o de staging.
- Conceder acceso en el evento incorrecto, como PIX generado en lugar de aprobado.
- Ignorar seguridad de webhooks hasta que comiencen los fallos.
- Asumir que datos faltantes de webhook significan ventas faltantes sin verificar solución de problemas de datos faltantes.
Preguntas frecuentes
¿Debo reconstruir el webhook cuando los logs muestran fallos?
Generalmente no. Corrige el endpoint o el manejo de eventos primero. Recrear el webhook sin corregir la causa raíz suele repetir el mismo fallo.
¿Dónde está la guía completa de configuración de webhooks?
Consulta planificar, probar y monitorear webhooks para selección de eventos, uso del simulador y flujo de monitoreo.
¿Zapier o Make pueden causar fallos de entrega?
Sí, si la URL catch, paso de filtro o automatización downstream falla. Revisa patrones de webhook con Zapier o Make.
¿Qué evidencia debo recopilar antes de escalar?
ID de webhook, tipo de evento, marca de tiempo, respuesta del endpoint, ID de venta cuando corresponda, y capturas de logs y tu sistema receptor.