How to Configure Your Site to Accept Webhooks from Stripe

Webhooks allow Stripe to send messages back to your WordPress site. Setting up webhooks is required for some functionality of WP Simple Pay such as sending emails, creating installment plans, allowing customers to update their subscription payment details, and using its integration with AffiliateWP.

WP Simple Pay attempts to create webhook endpoints automatically. In most cases manual configuration, as shown below, will not be necessary.

Add an Endpoint in Stripe

To add the appropriate webhook endpoints, in your Stripe Dashboard, go to Developers → Webhooks.

Click Add Endpoint, then add the URL found in WP Simple Pay → Settings → Stripe → Webhooks.

Do not enable Listen to events on Connected accounts as this will break WP Simple Pay webhook functionality.

You now will need to add the specific events to listen to by clicking the button labeled +Select events. After doing that, you can copy and paste each event listed below into the Select events to send → Search events search box.

After searching each term, click the checkbox to add it, and the search additional terms. Do not click Add events until you’ve checked all events listed below:

• 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

Details about the functionality of each of these events is shown at the bottom of this document.

When you’re done adding events, click Add endpoint to complete the process. After you add the endpoint, you should see the new URL listed in the webhooks settings.

Configuring the Webhook Signing Secret

Stripe can sign the webhook events it sends to your endpoints for added security, and we strongly recommend that you set this up.

To do so, retrieve your endpoint’s secret from your Dashboard’s webhooks settings. Select the added endpoint for which you want to obtain the secret, then click the Reveal button.

Then copy the signing secret from the Stripe Dashboard, head back to WP Simple Pay → Settings → Stripe → Webhooks in your WordPress admin, then paste it into the Endpoint Secret text box for the current payment mode.

Repeat in Test Mode

A webhook endpoint must also be created in Test Mode. Switch the Test mode toggle at the top right of the Stripe dashboard and repeat the steps above.

Event Type Descriptions

invoice.payment_succeeded

• Used to increment installment plans and send “Payment Confirmation” and “Payment Notification” emails for Subscriptions.
• Exposes the simpay_webhook_subscription_created action for further processing after a successful subscription creation.
• Exposes the simpay_webhook_invoice_payment_succeeded action for further processing after an invoice is processed.

<?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
);

Learn how to add custom code →

payment_intent.succeeded

• Sends the “Payment Confirmation” and “Payment Notification” emails for one-time payments.
• Exposes the simpay_webhook_payment_intent_succeeded action for further processing after successful payment

<?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
);

Learn how to add custom code →

invoice.upcoming

• Sends the “Upcoming Invoice” email reminder for updating a Payment Method. Learn more

checkout.session.completed

• Used to remove generated abandoned Stripe Checkout records.
• Exposes the simpay_webhook_checkout_session_completed action for further processing if needed.

charge.succeeded

• Sends the “Payment Confirmation” and “Payment Notification” emails for one-time payments using ACH Debit.
• Exposes the simpay_webhook_charge_succeeded action for further processing after successful payment

charge.failed

• Exposes the simpay_webhook_charge_failed action for further processing after a Charge fails.

Frequently Asked Questions

Are webhooks required?

Webhooks are not required to process payments, and when a webhook fails that does not indicate that a payment has failed to process. However, webhooks are utilized to power functionality such as fraud detection, email receipts, upcoming invoice notifications, and managing installment plans.

Webhooks are required to utilize email verification when fraud is detected.

Even if you are not using these features currently it is highly recommend to ensure you have configured the webhook endpoint correctly to avoid confusion if you decide to enable these features in the future, or if WP Simple Pay requires these functionalities for future features.

Why do I see “WP Simple Pay may not be functioning correctly.”

WP Simple Pay attempts to alert you of possible webhook endpoint misconfiguration or error to avoid interruption of features that utilize webhook functionality (emails, installment plans, etc). If WP Simple Pay is not able to verify an expected webhook event you will see a notification bubble within the plugin settings and the error message “WP Simple Pay may not be functioning correctly.”

How do I fix a misconfigured webhook endpoint?

To resolve a possible webhook endpoint misconfiguration, visit Developers → Webhooks in your Stripe dashboard (if you are in Test Mode, view your test mode endpoints).

Under Hosted endpoints you should see an entry containing the WP Simple Pay webhook event receiver: wp-json/wpsp/v1/webhook-receiver. If you do not see this endpoint, please complete the configuration steps outlined at the start of this article.

Click the WP Simple Pay endpoint URL to view the endpoint’s configuration. Here you will find a list of webhook events that have been sent to the endpoint.

Click the Failed tab to list any events that have failed.

If you have failed webhook events, selecting one of the entries will reveal the response received from the endpoint URL. This response often contains information on why the endpoint has failed to process the event in the Response section.

Failed to connect to remote host

Stripe was unable to communicate with your server. Please ensure your web server is responding to requests, and specifically is able to respond to any of Stripe’s fully qualified domain names. and IP addresses.

No signatures found matching the expected signature for payload

Stripe was unable to verify webhook event data using the signing secrets supplied in WP Simple Pay → Settings → Stripe → Webhooks. While viewing your webhook endpoint, click Reveal under Signing Secret and update your signing secret settings in WP Simple Pay for each payment mode.

404 ERR <!DOCTYPE html>

The webhook endpoint URL is incorrect and pointing to a 404 page not found. Visit WP Simple Pay → Settings → Stripe → Webhooks to find the correct value of your webhook endpoint URL and update the endpoint in Stripe.

I have verified my endpoint settings, why am I still seeing an error?

WP Simple Pay is purposely overly responsive to possible misconfigurations to ensure a true error does not go unnoticed. However, it is still possible to receive false positive notifications of a misconfigured webhook event. This can occur if there is a longer than average delay in Stripe sending the event data, or in some cases of Stripe Checkout where the off-site payment page is abandoned.

If you have verified there are no failed webhook endpoint event on your endpoint then you can disable the configuration notification by following the steps below.

Can I disable webhook configuration notifications?

As mentioned previously, it is highly recommended to properly configure and keep your webhook endpoint enabled. However, at your own risk, if you do not want be alerted of any potential misconfigurations or improperly received events you may permanently dismiss the notification in WP Simple Pay → Settings → Stripe → Webhooks by clicking Do not show again.