Setting up webhooks

Why do you need webhooks?

There is a one-way communication between WP Full Stripe and Stripe by default; the plugin sends requests to Stripe via the Stripe API.

Stripe webhooks make it possible to send messages in the other direction, so Stripe can notify the plugin when certain events occur.

WP Full Stripe is functional without webhooks, but webhooks are required to use the plugin to its full potential.

Which features require webhooks?

For working properly, the following features require webhooks:

• Payment in installments -type subscription plans
• Syncronizing charge status from Stripe to the plugin
  (For example, you made a refund in Stripe, not in WP admin)

How to set up webhooks

Setup procedure in a nutshell

1. Write down the Stripe webhook URL of the plugin on the “Full Stripe / Settings / Stripe account” page in WP admin.

2. Go to the Developers / Webhooks page on the Stripe dashboard.

3. Press the “Add endpoint” button, and fill in the form as follows:
   • Endpoint URL: Paste the webhook URL of the plugin
   • Select events to listen to: Select the following events:
     • customer.subscription.deleted
     • invoice.payment_succeeded
     • invoice.created
     • charge.succeeded
     • charge.updated
     • charge.refunded
     • charge.pending
     • charge.failed
     • charge.expired
     • charge.captured

4. Switch to live mode

5. Repeat step 3) in live mode

Setup procedure with screenshots

1. Write down the Stripe webhook URL you can find on the Full Stripe / Settings / Stripe account page

2. Go to the Developers / Webhooks page on the Stripe dashboard, and press the Add endpoint button

3. Configure the endpoint URL, and press the “Select events” button

4. Search/check the required events, and press the “Add events” button

When the events are added, press the “Add endpoint” button as well.

Make sure that only one webhook endpoint is set up per API mode (one for test, and one for live).

5. Switch to live mode

Switch to live mode by pressing the “Test mode” toggle in the top-tight corner:

6. Configure webhooks in live mode

Repeat steps 2), 3), and 4) in live mode.

Verifying webhooks on the Stripe dashboard

You can test your webhook setup by sending a test webhook event to the plugin.

Follow these steps:

1. Go to the Developers / Webhooks page on the Stripe dashboard, and select the webhook you’d like to test.
2. Press the “Send test event” button.
3. Select an event (any event will do), and press the “Send test webhook” button.
4. Verify in Stripe that sending the event was sucessful.
5. Verify in the plugin that receiving the event was successful.

Lets see the test procedure with screenshots:

1. Go to the Developers / Webhooks page on the Stripe dashboard, and select the webhook you’d like to test

2-3. Press the “Send test event” button, and send a test webhook

4. Verify that sending the event was successful

Verifying webhooks in WP Full Stripe

The final step to check the webhook endpoint status in the plugin on the “Full Stripe / Settings / Stripe account” page in WP admin.

If the webhook endpoint is configured properly, then you’ll see a green status indicator, and the time the last event was sent:

If the webhook endpoint is not configured properly, then you’ll see a grey status indicator:

Troubleshooting

You’ll find the most common errors with possible solutions in this section.

Webhook sent successfully but response is not empty

You are sending a test webhook from the Stripe dashboard.
Stripe says that “Test webhook sent successfully” but the response is not empty.

This usually means that there is a security plugin blocking the /wp-admin/admin-post.php URL.
Enable this URL for external callers, or add an exception so that the securiy plugin doesn’t block this URL.

Test webhook error: 503. Lookup <your_host>: no such host

This happens when are trying to send a webhook to local test environment, or there are issues with the DNS entries of <your_host>.

Verify your DNS settings, or use a globally accessible domain name for your test site - consider DynDNS or similar.

Test webhook error: 401

It means that the webhook endpoint rejected the webhook request.
It usually happens when the authentication token is not valid anymore. Compare the webhook URL in Stripe and in the plugin.

Test webhook error: 404

It means the webhook URL doesn’t exist.
Maybe a few characters of the URL were left off, consider copying and pasting the webhook URL to Stripe again.