Cómo solucionar el error 500 en un webhook de Stripe
1. Decide qué comprobar cuando Stripe recibe un error 500
Si Stripe muestra un 500 Internal Server Error al enviar un webhook, la primera decisión es distinguir si falla tu servidor o la configuración del endpoint. Yo empezaría por el registro del evento en el panel de control de Stripe y lo compararía con los registros de la aplicación: el código 500 indica que el servidor receptor informó de un error interno, pero por sí solo no explica su causa. No conviene volver a procesar pagos manualmente antes de comprobar si el evento ya produjo algún cambio en tu sistema.
Abre el evento y revisa la hora del intento, la URL de destino, la respuesta recibida y el historial de entregas. Después, busca en los registros de tu aplicación una petición coincidente. Si no aparece, revisaría la disponibilidad del servidor, el DNS, el proxy o el cortafuegos. Si aparece, comprobaría qué parte del código falló y si la petición llegó a una ruta distinta de la esperada. Esta secuencia ayuda a separar un problema de conectividad de un fallo de procesamiento.
2. Identifica la causa del fallo en el endpoint
Un 500 suele proceder de una excepción no controlada, una dependencia caída, una consulta fallida a la base de datos o una configuración incorrecta en el servidor. También puede ocurrir si el endpoint espera datos distintos de los que recibe, o si intenta procesar un evento sin validar primero su tipo. El cuerpo de la petición y la respuesta del servidor pueden aportar pistas, pero no publiques datos sensibles de clientes ni claves al compartir registros.
Comprueba también cómo verificas la firma del webhook. Stripe envía una cabecera Stripe-Signature; la validación debe utilizar el secreto del endpoint correspondiente, disponible en su configuración. Si el secreto no coincide, la validación debería rechazarse de forma controlada, normalmente con una respuesta de autenticación o petición inválida, no con un error interno. En muchos entornos, leer y transformar el cuerpo antes de verificar la firma altera los bytes originales y hace que la comprobación falle. Revisa la documentación de la biblioteca y el framework que utilizas para preservar el cuerpo sin procesar.
3. Corrige la entrega desde el panel, los métodos y la configuración
Panel de control: en Stripe, abre la sección de webhooks y selecciona el endpoint afectado. Revisa los intentos fallidos, la respuesta HTTP, la fecha y el evento concreto. Contrasta esos datos con los registros del servidor, usando marcas de tiempo y el identificador del evento. Evita basarte solo en el estado general del endpoint: cada entrega puede tener un resultado distinto.
Métodos de pago y eventos: comprueba que el endpoint escucha los tipos de evento que tu integración realmente procesa. Si un cambio reciente añadió un método de pago o un flujo nuevo, verifica que el código contempla sus estados y objetos antes de ejecutar acciones. No elimines métodos de pago para ocultar el error: el fallo puede estar en un manejador que no reconoce el evento, no en el método en sí.
Facturación y configuración: revisa el código del endpoint, las variables de entorno y el despliegue actual. Confirma que la URL es pública y usa
HTTPS, que el secreto de firma pertenece a ese endpoint y que el servidor conserva el cuerpo original para validar la petición. Añade registro de errores que identifique el evento sin incluir datos de tarjeta, secretos ni información personal innecesaria. Cuando corrijas la causa, utiliza la opción de reintento de Stripe para comprobar la entrega; verifica antes si el evento ya se procesó.
4. Evita duplicados y fallos recurrentes
Diseña el manejador para que sea idempotente: Stripe puede volver a enviar una entrega y tu aplicación debe evitar aplicar dos veces el mismo efecto. Una práctica habitual es guardar el identificador del evento procesado y comprobarlo antes de cambiar el estado de una factura, pedido o suscripción. Si el sistema necesita más tiempo para completar tareas, valida la petición, registra el evento de forma segura y responde con éxito cuando corresponda; después, procesa el trabajo en segundo plano con control de errores.
Mantén una monitorización de las entregas fallidas y de la salud del endpoint, especialmente después de cambios de código, secretos o infraestructura. Limita el acceso a los registros y rota cualquier credencial que se haya expuesto. También conviene probar los manejadores con distintos eventos y escenarios de error antes de desplegarlos. No marques manualmente una factura como pagada ni repitas un cobro solo porque un webhook falló: consulta el estado del objeto en Stripe y en tu sistema para evitar desajustes.
5. Respuestas rápidas sobre los webhooks con error 500
Q1. ¿Un error 500 significa que Stripe ha rechazado el pago?
A1. No necesariamente. El código describe la respuesta del endpoint receptor, no confirma por sí solo si un pago se completó o se rechazó. Comprueba el estado del objeto de pago en Stripe y la operación registrada en tu aplicación. Evita crear un cobro nuevo hasta aclarar si el anterior tuvo efecto.
Q2. ¿Puedo volver a enviar el evento después de corregir el servidor?
A2. Sí, puedes usar el reintento disponible en el panel de control, pero primero verifica qué cambios pudo realizar la aplicación antes de fallar. El manejador debe ser idempotente para que una entrega repetida no duplique acciones. Compara el identificador del evento con los registros de procesamiento y confirma el resultado en ambos sistemas.
Q3. ¿Qué diferencia hay entre un error 500 y un fallo de firma?
A3. Un error 500 suele indicar que el servidor terminó la petición con una excepción o un fallo interno. Un problema de firma significa que no se pudo validar la autenticidad de la solicitud, a menudo por un secreto incorrecto o por modificar el cuerpo antes de verificarlo. Revisa la respuesta y los registros del endpoint para distinguirlos. No desactives la verificación de firma como solución: corrige la configuración o el tratamiento del cuerpo.