1. Home
  2. Functionality
  3. How to Configure Your Site to Accept Webhooks from Stripe

How to Configure Your Site to Accept Webhooks from Stripe

Starting with WP Simple Pay release 4.4.2, we make an attempt to create webhook endpoints automatically. In most cases manual configuration, as shown below, will not be necessary.

Configure Webhook Endpoints

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.

To add the appropriate webhook endpoints, in your Stripe Dashboard, go to Developers > Webhooks (direct link).

We recommend creating two webhook endpoints: one in Test Mode and in Live Mode. If you don’t create one for each payment mode now, you’ll need to repeat the process detailed below after toggling payment modes in WP Simple Pay.

Click Add Endpoint, then add the URL found in WP Simple Pay > Settings > Stripe > Webhooks. At the same time that you add your endpoint, you will need to add the events to listen to by clicking the button labeled +Select events.

After doing that, check the Select all events checkbox as shown below, then click the Add events button located near the bottom of the page.

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

When you’re done adding events, click Add endpoint button at the bottom of the page to complete the process.  

After you add the endpoint, you should see the new URL listed in the webhooks settings. 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 an endpoint for which you want to obtain the secret, then click the Reveal button.

We recommend creating two webhook endpoints: one in Test Mode and in Live Mode. If you don’t create one for each payment mode now, you’ll need to repeat the process detailed below after toggling payment modes in WP Simple Pay.

Stripe, Live Mode Dashboard: https://dashboard.stripe.com/dashboard

Stripe, Test Mode Dashboard: https://dashboard.stripe.com/test/dashboard

Then copy the signing secret from the Stripe Dashboard, head back to the Stripe Setup tab in your WP admin, then paste it into the Test Endpoint Secret text box.

Your webhooks are now set up and secure.

If you are comfortable with advanced configurations, you may wish to specify which webhook events to listen for. If so, please see the Advanced Stripe Webhook Setup document.

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 email receipts, upcoming invoice notifications, and managing installment plans.

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.

WP Simple Pay webhook event receiver

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:

View failed webhook events

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:

Failed webhook event

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:

Update an existing webhook endpoint

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”

Was this article helpful?

Still stuck? How can we help?
Updated on May 26, 2022