Configurar el webhook de Stripe

Por qué necesita un webhook de Stripe

Stripe Checkout confirma el primer pago cuando un inquilino se suscribe a un plan. Pero la facturación por suscripción no termina tras el primer pago.

Un webhook de Stripe permite que Stripe notifique a su sitio Booknetic SaaS cuando ocurran eventos importantes de suscripción más adelante, como:

• se paga con éxito la renovación de la suscripción
• se cancela una suscripción en Stripe

Sin un webhook funcional, Stripe puede tener el estado de suscripción correcto, pero Booknetic SaaS puede no actualizarse en tiempo real. Por ejemplo, un inquilino puede pagar una renovación en Stripe, pero el periodo de suscripción en Booknetic SaaS puede no extenderse hasta que el webhook esté configurado correctamente.

En resumen: Stripe es donde se realiza el pago de la suscripción; el webhook es la forma en que Booknetic SaaS se entera del resultado.

Antes de empezar

Asegúrese de que ya tiene:

• Stripe habilitado en Booknetic SaaS
• su Stripe Publishable key y Secret key añadidos en Booknetic SaaS ajustes
• acceso a su Stripe Dashboard
• su dominio web en producción usando HTTPS

Su versión de la API de Stripe debería ser compatible con Booknetic SaaS. La integración actual de Booknetic SaaS Stripe establece la versión de la API de Stripe a:

2025-07-30.basil

Si usa una cuenta Stripe muy antigua o una configuración de API antigua y llegan eventos de webhook pero las renovaciones de suscripción siguen sin actualizarse en Booknetic SaaS, contacte con soporte para que lo revise.

Copie su URL de webhook de Booknetic SaaS

Su URL de webhook utiliza su propio dominio web y esta acción de webhook de Booknetic SaaS:

https://your-domain.com/?booknetic_saas_action=stripe_webhook

Sustituya https://your-domain.com por su dominio real de plataforma SaaS.

Por ejemplo:

https://example.com/?booknetic_saas_action=stripe_webhook

Importante: Use ?booknetic_saas_action=stripe_webhook. No utilice URLs de webhook antiguas o de aspecto diferente como ?bkntcsaas_stripe_webhook=1.

Añadir el endpoint del webhook en Stripe

Para todos los pasos siguientes en Stripe Dashboard, consulte la documentación oficial de Stripe para capturas de pantalla actuales de la UI: https://docs.stripe.com/webhooks.

En su Stripe Dashboard:

1. Abra Developers.
2. Vaya a Webhooks.
3. Haga clic en Add endpoint o Create an event destination. Stripe puede mostrar cualquiera de las dos palabras dependiendo de la versión de su panel de control.
4. Elija su propia cuenta Stripe como fuente del evento. No elija cuentas conectadas a menos que esté configurando intencionadamente una aplicación Stripe Connect.
5. Pegue su URL de webhook de Booknetic SaaS en el campo URL del endpoint:

https://your-domain.com/?booknetic_saas_action=stripe_webhook

6. Añada una descripción clara, por ejemplo:

Booknetic SaaS billing webhook

7. Seleccione los eventos listados en la siguiente sección.
8. Guarde el punto final.

Seleccione los eventos de Stripe requeridos

Booknetic SaaS escucha estos eventos de Stripe de webhook:

Stripe evento

Qué actualice en Booknetic SaaS

invoice.paid

Confirma las renovaciones pagadas y amplía el periodo de suscripción de los inquilinos

customer.subscription.deleted

Marca la suscripción como cancelada/cancelada en Booknetic SaaS

Suma ambos eventos al punto final:

invoice.paid
customer.subscription.deleted

No se requieren otros eventos Stripe para la sincronización de suscripción actual de Booknetic SaaS.

Copie el secreto de firma del webhook de Stripe

Después de crear el endpoint, ábrelo en Stripe y revela el Signing secret.

Normalmente empieza con:

whsec_

Copie este valor. Lo pegará en Booknetic SaaS en el siguiente paso.

Mantén este secreto en privado. No lo envíes en chat público, capturas de pantalla ni correos electrónicos.

Añada el secreto del webhook en Booknetic SaaS

En su área administrativa de WordPress:

1. Abra Booknetic SaaS.
2. Vaya a Settings.
3. Abra la sección Payment Gateways o Stripe.
4. Encuentra el campo Webhook secret.
5. Pegue el whsec_... secreto de firma de Stripe.
6. Guarde la configuración.

Booknetic SaaS utiliza este secreto para comprobar que las solicitudes de webhook realmente provienen de Stripe. Si el secreto falta o es incorrecto, la solicitud de webhook es rechazada.

Prueba el gancho de la red

Después de guardar el endpoint y el secreto del webhook, pruebe la configuración desde Stripe.

En Stripe:

1. Abra Developers → Webhooks.
2. Abra Booknetic SaaS endpoint webhook que ha creado.
3. Utiliza la opción de prueba/envío de Stripe para el endpoint.
4. Envía un evento de prueba para uno de los eventos suscritos, como invoice.paid.
5. Compruebe el resultado de la entrega.

Una entrega exitosa debería devolver una respuesta HTTP 200.

Un evento de prueba Stripe es útil para comprobar que Stripe puede acceder a su sitio y que el secreto de firma es aceptado. Para confirmar la sincronización completa de la suscripción, ejecuta también un flujo real de suscripción de prueba en Stripe modo de prueba y confirma que la suscripción al inquilino se actualice en Booknetic SaaS.

Cómo confirmar que funciona

Tras la configuración, puede verificar el webhook en dos lugares:

1. Stripe Dashboard → Webhooks

• Abra el punto final.
  • Revise las entregas recientes.
  • Las entregas exitosas deben mostrar una respuesta 2xx, normalmente 200.

2. Booknetic SaaS estado de facturación/suscripción del inquilino

• Completar un pago de suscripción de prueba.
  • Confirmar que la suscripción al inquilino se activa activamente.
  • Cancelar la suscripción de prueba en Stripe.
  • Confirmar Booknetic SaaS actualizar el estado de la suscripción después de que se entregue el webhook.

Solución de problemas

Stripe muestra 400 en vez de 200

Una respuesta de un 400 suele significar Booknetic SaaS no pudieron verificar la solicitud de webhook.

Causas más comunes:

• el secreto del webhook en Booknetic SaaS está vacío
• se pegó el secreto incorrecto whsec_...
• el secreto pertenece a un endpoint de webhook diferente Stripe
• el endpoint se recreó en Stripe, pero el nuevo secreto no se copió en Booknetic SaaS

Solución:

1. Abra el endpoint del webhook en Stripe.
2. Revela/copie el secreto de firma actual.
3. Pégalo de nuevo en Booknetic SaaS → Settings → Stripe → Webhook secret.
4. Guarde la configuración.
5. Envía otro evento de prueba desde Stripe.

Una suscripción fue cancelada en Stripe, pero todavía está activa en Booknetic SaaS

Esto generalmente significa que Booknetic SaaS no recibió ni aceptó el evento de webhook customer.subscription.deleted.

Verifica:

• que la URL del endpoint del webhook sea correcta
• que el endpoint esté suscrito a customer.subscription.deleted
• que las entregas recientes de Stripe muestren HTTP 200
• que el secreto del webhook en Booknetic SaaS coincida con el secreto de firma actual del endpoint

Se pagó una renovación en Stripe, pero la fecha de expiración del inquilino no se actualizó

Las renovaciones se actualizan mediante el evento de webhook invoice.paid.

Verifica:

• que el endpoint esté suscrito a invoice.paid
• que Stripe muestre una entrega exitosa para el evento de la factura
• que la respuesta de la entrega sea 200
• que el secreto del webhook sea correcto

Si Stripe muestra que el evento se entregó correctamente pero Booknetic SaaS todavía no se actualice, contacte al soporte con el ID del evento Stripe y el inquilino afectado.

Cambié el endpoint de webhook en Stripe y ahora dejó de funcionar

Cuando crea un nuevo endpoint, Stripe genera un nuevo secreto de firma. Copie el nuevo valor whsec_... en Booknetic SaaS y guarde la configuración nuevamente.

Mi inquilino pregunta: "¿Dónde puedo actualizar mi tarjeta?"

Booknetic SaaS no incluye actualmente un botón Stripe Customer Portal para que los inquilinos actualicen su tarjeta por sí mismos.

Opciones recomendadas:

• Pide al inquilino cancelar la suscripción actual y suscribirse de nuevo al mismo plan. El nuevo proceso de pago les permitirá ingresar una nueva tarjeta.
• Si el inquilino necesita ayude sin cancelar/re-suscribirse, el propietario de la plataforma debe ayudar desde Stripe Dashboard o contacter al soporte para asistencia manual.

No digas a los inquilinos que pueden actualizar su tarjeta desde un enlace Booknetic SaaS Stripe Customer Portal, porque ese portal de autoservicio actualmente no está conectado a Booknetic SaaS.

Dónde encontrar capturas de pantalla de Stripe Dashboard

Esta página intencionalmente no incrusta capturas de pantalla de Stripe Dashboard. Stripe actualice regularmente su UI del Dashboard, y las capturas de pantalla desactualizadas crean más confusión de la que previenen.

Para capturas de pantalla actuales y oficiales de las pantallas de configuración del endpoint Webhooks, consulte la propia documentación de Stripe: https://docs.stripe.com/webhooks.