¿Qué hace Payment Webhook Doctor?
Comience con la evidencia, no con un reenvío. Reenviar un evento a un manejador roto puede repetir sus efectos secundarios.
Atienda una tarea a la vez
| Problema | Leer |
|---|---|
| Firma falla, secreto incorrecto, cuerpo parseado, entrega antigua | references/signatures.md |
| Crédito duplicado, cumplimiento retrasado, fallo después del éxito, reembolsos fuera de orden | references/reconciliation.md |
| 4xx/5xx/timeout, recuperación, evento faltante, despliegue en producción | references/incident-playbook.md |
| Necesita hechos de protocolo verificados y límites de versión | references/sources.md |
| Necesita un adaptador que no sea Stripe / M-Pesa | references/provider-boundary.md |
Flujo de trabajo
- Establezca el alcance: proveedor, instantánea versus evento fino, modo de prueba/vivo, cuenta conectada, framework de endpoint y versión de API. Pregunte solo por los hechos faltantes que cambien el diagnóstico.
- Inspeccione el código del manejador, las migraciones, el monto/moneda esperado del pedido, el mapeo de PaymentIntent creado por el servidor y los metadatos de entrega redactados. Mantenga los secretos de firma en variables de entorno locales. No pida a los usuarios que peguen secretos o cuerpos de clientes en el chat.
- Verifique los bytes exactos de la solicitud sin procesar antes de parsear JSON. Prefiera el SDK oficial de Stripe para un manejador desplegado. El verificador incluido sin dependencias es una referencia de diagnóstico pequeña e inspeccionable, no un SDK de reemplazo.
- Use las herramientas locales a continuación para reproducir la falla con fixtures sintéticos primero. Clasifique la evidencia como observada, inferida o no verificada. Una firma válida autentica una entrega; no prueba que el pedido deba cumplirse.
- Repare la causa más pequeña y agregue una prueba de regresión. Vincule los pagos a un pedido de confianza del lado del servidor; compare monto, moneda, alcance de cuenta y modo. Mantenga la bandeja de entrada, la actualización del libro mayor y la intención de efectos secundarios en una sola transacción de base de datos.
- Verifique duplicados, eventos distintos para el mismo objeto, reinicio, entrega fuera de orden, eventos fallidos y reembolsos parciales/totales. No use las marcas de tiempo de los eventos como mecanismo de ordenamiento total.
- Entregue hallazgos, parche, evidencia de prueba, requisitos de integración no resueltos y un plan explícito de reversión/recuperación. No despliegue, reenvíe eventos en vivo, emita reembolsos ni transfiera dinero sin el flujo de trabajo autorizado del usuario.
Herramientas locales
Ejecute desde la raíz de esta habilidad:
npm test
npm run demo
Inspeccione un fixture guardado en modo de prueba usando su reloj de fixture documentado:
export DOCTOR_FIXTURE_SECRET='fixture_only_not_a_live_secret'
node scripts/doctor.mjs --body fixtures/payment.json --header fixtures/signature.txt \
--secret-env DOCTOR_FIXTURE_SECRET --fixture-now 1794130000 \
--normalized-out /tmp/payment-doctor-event.json
python3 scripts/ledger.py --db /tmp/payment-doctor-reference.sqlite \
--orders fixtures/orders.json < /tmp/payment-doctor-event.json
La exportación se niega a sobrescribir un archivo existente. Use una ruta de salida nueva o elimine deliberadamente su propia salida sintética. La CLI de Python escribe solo en la base de datos SQLite local nombrada explícitamente. Espera la salida normalizada confiable del verificador; no verifica firmas por sí misma. Nunca la exponga como un endpoint de webhook público.
El informe de diagnóstico normal excluye datos de clientes, cargas útiles sin procesar y firmas. Una exportación normalizada explícita retiene identificadores y montos enteros necesarios para la conciliación local. Manténgala privada y fuera del control de versiones.
--fixture-now es solo para eventos de prueba sintéticos antiguos; rechaza entrada en modo vivo. Omita para una entrega actual ordinaria. El libro de referencia rechaza eventos en modo vivo, nunca llama a Stripe y nunca envía filas de la bandeja de salida.
Informe requerido
- Resultado: qué sucedió y si se reproduce.
- Evidencia: archivos/líneas, metadatos de entrega saneados, comandos exactos, resultados observados.
- Causa raíz: causa confirmada frente a hipótesis restantes.
- Reparación: parche mínimo más implicaciones de migración/rellenado.
- Matriz de regresión: duplicado, reinicio, desajuste de alcance, monto/moneda incorrectos, ordenamiento, casos de reembolso.
- Traspaso operacional: evidencia de integración en modo de prueba aún necesaria; criterios de reproducción segura y reversión.
Límites
El soporte es intencionalmente limitado: eventos de instantánea de Stripe payment_intent.succeeded, payment_intent.payment_failed y eventos de objeto de reembolso. Los eventos finos, derechos de suscripción, sesiones de Checkout, disputas, semántica de pago multicaptura, tarifas de aplicación, impuestos y transferencias de Connect necesitan adaptadores dedicados. Un resultado sin hallazgos no es una certificación de seguridad ni una prueba de que los fondos llegaron. Consulte las referencias antes de extender.