Cómo configurar tu sitio para aceptar webhooks de Stripe

Los webhooks permiten a Stripe enviarte mensajes a tu sitio de WordPress. La configuración de webhooks es obligatoria para algunas funcionalidades de WP Simple Pay, como enviar correos electrónicos, crear planes de pago a plazos, permitir a los clientes actualizar los detalles de pago de su suscripción y usar su integración con AffiliateWP.

WP Simple Pay intenta crear endpoints de webhook automáticamente. En la mayoría de los casos, la configuración manual, como se muestra a continuación, no será necesaria.

Añadir un endpoint en Stripe

Para añadir los endpoints de webhook apropiados, en tu Panel de Stripe, ve a Desarrolladores → Webhooks.

Haz clic en Añadir endpoint, luego añade la URL que se encuentra en WP Simple Pay → Ajustes → Stripe → Webhooks.

No habilites Escuchar eventos en cuentas conectadas, ya que esto romperá la funcionalidad de los webhooks de WP Simple Pay.

Ahora necesitarás añadir los eventos específicos a los que escuchar haciendo clic en el botón etiquetado como +Seleccionar eventos. Después de hacerlo, puedes copiar y pegar cada evento listado a continuación en el cuadro de búsqueda Seleccionar eventos a enviar → Buscar eventos .

Después de buscar cada término, haz clic en la casilla de verificación para añadirlo y buscar términos adicionales. No hagas clic en Añadir eventos hasta que hayas marcado todos los eventos listados a continuación:

• payment_intent.processing
• payment_intent.succeeded
• charge.failed
• charge.refunded
• charge.succeeded
• checkout.session.completed
• customer.subscription.deleted
• customer.subscription.updated
• invoice.payment_succeeded
• invoice.upcoming

Los detalles sobre la funcionalidad de cada uno de estos eventos se muestran al final de este documento.

Cuando hayas terminado de añadir eventos, haz clic en Añadir endpoint para completar el proceso. Después de añadir el endpoint, deberías ver la nueva URL listada en la configuración de webhooks.

Configuración del secreto de firma de webhooks

Stripe puede firmar los eventos de webhook que envía a sus endpoints para mayor seguridad, y recomendamos encarecidamente que configure esto.

Para hacerlo, recupere el secreto de su endpoint desde la configuración de webhooks de su Dashboard. Seleccione el endpoint agregado para el cual desea obtener el secreto y, a continuación, haga clic en el botón Revelar.

Luego, copie el secreto de firma del Dashboard de Stripe, regrese a WP Simple Pay → Ajustes → Stripe → Webhooks en su administrador de WordPress y, a continuación, péguelo en el cuadro de texto Secreto del endpoint para el modo de pago actual.

Repetir en modo de prueba

También se debe crear un endpoint de webhook en Modo de prueba. Cambie el interruptor Modo de prueba en la parte superior derecha del dashboard de Stripe y repita los pasos anteriores.

Descripciones de tipos de eventos

invoice.payment_succeeded

• Se utiliza para incrementar los planes de pago a plazos y enviar correos electrónicos de “Confirmación de pago” y “Notificación de pago” correos electrónicos para Suscripciones.
• Expone la acción simpay_webhook_subscription_created para procesamiento adicional después de una creación de suscripción exitosa.
• Expone la acción simpay_webhook_invoice_payment_succeeded para procesamiento adicional después de que se procesa una factura.

<?php
add_action(
	'simpay_webhook_subscription_created',
	/**
	 * Fires when a subscription is created in Stripe.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event        $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\Subscription $subscription Stripe Subscription.
	 */
	function( $event, $subscription ) {
		// Do something.
	},
	10,
	2
);

<?php
add_action(
	'simpay_webhook_invoice_payment_succeeded',
	/**
	 * Fires when a subscription invoice payment has succeeded.
	 * Does not fire for the subscription creation (first) invoice.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event        $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\Invoice      $invoice Stripe Invoice object.
	 * @param \SimplePay\Vendor\Stripe\Subscription $subscription Stripe Subscription object.
	 */
	function( $event, $invoice, $subscription ) {
		// Do something.
	},
	10,
	3
);

Aprenda cómo agregar código personalizado →

payment_intent.succeeded

• Envía los correos electrónicos de “Confirmación de pago” y “Notificación de pago” correos electrónicos para pagos únicos.
• Expone la acción simpay_webhook_payment_intent_succeeded para procesamiento adicional después de un pago exitoso

<?php
add_action(
	'simpay_webhook_payment_intent_succeeded',
	/**
	 * Fires when a one-time payment has succeeded.
	 * 
	 * @param \SimplePay\Vendor\Stripe\Event         $event Stripe webhook event.
	 * @param \SimplePay\Vendor\Stripe\PaymentIntent $paymentintent Stripe PaymentIntent.
	 */
	function( $event, $paymentintent ) {
		// Do something.
	},
	10,
	2
);

Aprenda cómo agregar código personalizado →

invoice.upcoming

• Envía el recordatorio de correo electrónico de “Próxima factura” correo electrónico para actualizar un método de pago. Más información

checkout.session.completed

• Se utiliza para eliminar registros generados de Stripe Checkout abandonados.
• Expone la acción simpay_webhook_checkout_session_completed para procesamiento adicional si es necesario.

charge.succeeded

• Envía los correos electrónicos de “Confirmación de pago” y “Notificación de pago” correos electrónicos para pagos únicos utilizando Débito ACH.
• Expone la acción simpay_webhook_charge_succeeded para procesamiento adicional después de un pago exitoso

charge.failed

• Expone la acción simpay_webhook_charge_failed para procesamiento adicional después de que falla un cargo.

Preguntas frecuentes

¿Son necesarios los webhooks?

Los webhooks no son necesarios para procesar pagos, y cuando un webhook falla, eso no indica que un pago no se haya procesado. Sin embargo, los webhooks se utilizan para potenciar funcionalidades como la detección de fraude, recibos por correo electrónico, notificaciones de próximas facturas y la gestión de planes de pago a plazos.

Los webhooks son necesarios para utilizar la verificación por correo electrónico cuando se detecta fraude.

Incluso si no está utilizando estas funciones actualmente, se recomienda encarecidamente asegurarse de haber configurado el punto de conexión del webhook correctamente para evitar confusiones si decide habilitar estas funciones en el futuro, o si WP Simple Pay requiere estas funcionalidades para funciones futuras.

¿Por qué veo "WP Simple Pay puede no estar funcionando correctamente"?

WP Simple Pay intenta alertarle sobre una posible mala configuración o error en el punto de conexión del webhook para evitar la interrupción de las funciones que utilizan la funcionalidad del webhook (correos electrónicos, planes de pago a plazos, etc.). Si WP Simple Pay no puede verificar un evento de webhook esperado, verá una burbuja de notificación dentro de la configuración del plugin y el mensaje de error "WP Simple Pay puede no estar funcionando correctamente".

¿Cómo soluciono un punto de conexión de webhook mal configurado?

Para resolver una posible mala configuración del punto de conexión del webhook, visite Desarrolladores → Webhooks en su panel de Stripe (si está en Modo de prueba, vea sus puntos de conexión en modo de prueba).

En Puntos de conexión alojados debería ver una entrada que contiene el receptor de eventos de webhook de WP Simple Pay: wp-json/wpsp/v1/webhook-receiver. Si no ve este punto de conexión, complete los pasos de configuración descritos al principio de este artículo.

Haga clic en la URL del punto de conexión de WP Simple Pay para ver la configuración del punto de conexión. Aquí encontrará una lista de los eventos de webhook que se han enviado al punto de conexión.

Haga clic en la pestaña Fallidos para listar cualquier evento que haya fallado.

Si tiene eventos de webhook fallidos, seleccionar una de las entradas revelará la respuesta recibida de la URL del punto de conexión. Esta respuesta a menudo contiene información sobre por qué el punto de conexión no pudo procesar el evento en la sección Respuesta.

Error al conectar con el host remoto

Stripe no pudo comunicarse con su servidor. Asegúrese de que su servidor web esté respondiendo a las solicitudes y, específicamente, que pueda responder a cualquiera de los nombres de dominio completos y direcciones IP de Stripe.

No se encontraron firmas que coincidan con la firma esperada para el payload

Stripe no pudo verificar los datos del evento del webhook utilizando los secretos de firma proporcionados en WP Simple Pay → Ajustes → Stripe → Webhooks. Mientras ve su punto de conexión de webhook, haga clic en Revelar en Secreto de firma y actualice sus ajustes de secreto de firma en WP Simple Pay para cada modo de pago.

404 ERR <!DOCTYPE html>

La URL del punto de conexión del webhook es incorrecta y apunta a una página 404 no encontrada. Visite WP Simple Pay → Ajustes → Stripe → Webhooks para encontrar el valor correcto de su URL de punto de conexión de webhook y actualice el punto de conexión en Stripe.

He verificado la configuración de mi punto de conexión, ¿por qué sigo viendo un error?

WP Simple Pay es deliberadamente demasiado sensible a posibles errores de configuración para garantizar que un error real no pase desapercibido. Sin embargo, todavía es posible recibir notificaciones de falso positivo de un evento de webhook mal configurado. Esto puede ocurrir si hay un retraso más largo de lo normal en el envío de los datos del evento por parte de Stripe, o en algunos casos de Stripe Checkout donde se abandona la página de pago externa.

Si ha verificado que no hay eventos de punto de conexión de webhook fallidos en su punto de conexión entonces puede deshabilitar la notificación de configuración siguiendo los pasos a continuación.

¿Puedo deshabilitar las notificaciones de configuración de webhooks?

Como se mencionó anteriormente, se recomienda encarecidamente configurar correctamente y mantener habilitado su punto de conexión de webhook. Sin embargo, bajo su propio riesgo, si no desea que se le alerte de posibles errores de configuración o eventos recibidos de manera incorrecta, puede descartar permanentemente la notificación en WP Simple Pay → Configuración → Stripe → Webhooks haciendo clic en No volver a mostrar.