Cuando un pago se completa en 0fee.dev -- ya sea a través de la página de checkout de Stripe, el USSD push de Hub2 o el flujo de redirección de PaiementPro -- el comerciante necesita saberlo. No pueden consultar la API continuamente. La solución son los webhooks: solicitudes HTTP POST enviadas desde 0fee.dev al servidor del comerciante cada vez que ocurre un evento de pago. Pero la entrega de webhooks es más difícil de lo que parece. Los servidores de los comerciantes se caen. Las redes fallan. Los firewalls bloquean solicitudes. El sistema de webhooks debe manejar todo esto de manera confiable.
Cada entrega de webhook se firma con HMAC-SHA256 para que el comerciante receptor pueda verificar que la solicitud genuinamente provino de 0fee.dev. El formato de firma t=timestamp,v1=signature sigue la convención popularizada por Stripe. Incluir el timestamp en el mensaje firmado previene ataques de repetición.
El sistema genera webhooks en cada punto significativo del ciclo de vida del pago: payment.created, payment.completed, payment.failed, payment.expired, payment.cancelled, refund.created, refund.completed, refund.failed, checkout.completed, checkout.expired.
Cuando una entrega falla, el sistema reintenta con backoff exponencial: inmediato, 1 minuto, 5 minutos, 30 minutos, 2 horas, 8 horas. La ventana total de reintento abarca aproximadamente 10 horas y 36 minutos.
Si el endpoint de webhook de un comerciante falla 10 veces consecutivas en cualquier evento, el sistema desactiva automáticamente la entrega de webhooks para esa aplicación y notifica al comerciante por email. Pueden reactivarlo desde el panel después de corregir el problema subyacente.
Cada intento de entrega se registra en la tabla webhook_deliveries, sirviendo tres propósitos: depuración, visibilidad en el panel y analíticas.
Este artículo es parte de la serie "Cómo construimos 0fee.dev". 0fee.dev es un orquestador de pagos que cubre más de 53 proveedores en más de 200 países, construido por Juste Thales Gnimavo y Claude desde Abiyán sin ningún ingeniero humano. Sigue la serie para conocer la historia completa de construcción.