Wondering what WooCommerce webhooks are? Maybe you’ve seen the webhooks screen in your WooCommerce settings or you’re simply curious about how they work. Whatever the case, if you’re serious about growing your store it’s worth learning about webhooks.

Webhooks in WooCommerce are basically one way that you can send data to an URL when something happens in your store. It’s how WooCommerce can notify you about new orders in Slack, how stores can print a sticker for each new order, and how you can keep multiple systems and accounts in sync with your latest list of coupons.

In any case, it’s good to know how to use webhooks if you want to automatically push data from one app to another when customizing your WooCommerce site.

So in this post, we’ll go over the fundamentals of WooCommerce webhooks so you can start of creating and testing your own.

What is a WooCommerce Webhook?

A webhook is an event notification—known as a payload—sent to a URL you specify. You can configure webhooks to trigger events on one website to invoke behavior on another.

WooCommerce webhooks are useful for integrating the platform with third-party services and other external API that support them.

For example, in Robot Ninja we’re looking at using extending WooCommerce webhooks to implement a highly requested feature, which will automagically queue up tests for your store after any plugin or theme has been added or updated.

If you’re unfamiliar with webhooks and reading about them for the first time, it’s no surprise since they’re well-hidden in the WooCommerce settings.

Webhooks were originally introduced in WooCommerce 2.3 and can trigger events each time you add, edit delete orders, products, coupons or customers.

WooCommerce 3.5 introduced the Action Scheduler for delivering webhooks. This background processing library, which is used by the WooCommerce Subscriptions plugin, was merged into WooCommerce core to provide a robust, scalable, traceable job queue solution for processing large queues of tasks in the background on WordPress.

Action Scheduler is close to our heart since it’s a Prospress production. It’s already in use on thousands of WooCommerce sites as part of WooCommerce Subscriptions.

Creating WooCommerce Webhooks

To create a new webhook, go to WooCommerce > Settings > Advanced > Webhooks.

If you’re using a version of WooCommerce older than 3.4.0, you’ll find webhooks located in WooCommerce > Settings > API > Webhooks.

A webhook in WooCommerce is made up of several different components. Let’s break it down.

Name

The name of the webhook, which only store admins see. If left empty, WooCommerce will auto-generate a name, such as “Webhook created on [date and time of creation].” It’s useful to give your webhook a name that explains what it is for or what it does.

Status

There are three statues that you can assign a webhook:

• Active – Webhook payload will be sent when event is triggered.
• Paused – Webhook does not deliver.
• Disabled – A webhook is automatically set to disabled if it was previously active and there was an issue with the delivery.

Topic

This is an action, or trigger, for the webhook. In WooCommerce, there are 16 available topics to choose from. Any extras you see in your list will have been added by other plugins. For example, below you can see WooCommerce Subscriptions provides topics for creating, updating, deleting and switching subscriptions.

Topics usually describe an event or action associated with a WooCommerce object type—i.e. Coupon, Order, Product, or Customer—such as Order Created, Coupon Restored, etc.

If you select Action as your topic, a new field will display allowing you to create a webhook that is triggered when a WooCommerce action occurs. This topic opens up webhooks to be used in many interesting ways. For example, you could create a webhook that fires when the woocommerce_low_stock action occurs so you can automatically react and preorder new stock.

For a full list of WooCommerce hookable actions, check out the WooCommerce Docs Hook Reference guide.

Delivery URL

This is the URL you want the payload to be sent to. Payloads are sent as POST requests to this URL.

Secret

The secret key generates a hash of the delivered payload and is provided in the request headers. If you leave this field empty, it defaults to using a consumer key for the currently logged in admin user.

API Version

The API version allows you to choose which format the payload will be delivered in. For the most part, using the default option is perfectly fine. If you’re creating a webhook for some third party integration that only supports the legacy v3 version of the API, then you can set the data to that format.

Testing WooCommerce Webhooks

Before we dive into testing webhooks in WooCommerce, it’s important to know that webhooks delivery happens in the background. This means that a webhook will first need queued and the job processed before you’ll see the delivery of the webhook.

For testing purposes, you can choose to have a webhook deliver the payload immediately using the following snippet:

apply_filters( 'woocommerce_webhook_deliver_async', '__return_false' );

For the purposes of this post, we’re going to stick to the default async behavior, and the webhook we’re going to use is with the topic Order Updated.

When you first activate any new or existing webhook, WooCommerce will immediately try to send a test POST request with the new webhook ID as its payload. This is to check the delivery URL is working at the time of activation. If this request fails, the webhook will not be activated and will be set to disabled.

To help with testing webhooks, you need to know how to first trigger the webhook and, for the most part, the topic should be fairly self explanatory in terms of how to do it:

• Order Updated:
  • Purchase an order via the checkout
  • Change a billing address on an order using the “Edit Order” admin page
  • Update the order’s status
• Customer Created
  • Create a new user with the customer role
• Product Restored
  • Trash a product and then restore it

Let’s run through the steps required to test a webhook.

1. Visit RequestBin and create a fresh bin for testing. Keep your browser tab—we’ll need this bin URL in a moment.

2. Return to WooCommerce and create a new webhook if you haven’t already. In the “Delivery URL” field, paste in the bin URL you created with RequestBin.

3. Fill in the other fields for your webhook, set a topic—in this case, “Order updated”—and make sure your webhook is set to “Active” before saving.

4. Run through the steps required to trigger your webhook. For this example, since we’re testing Order Updated, we need to:

• Go to the orders table.
• Update the order status. I’m updating the status from “processing” to “completed” for order #1238.
• Click “Update.”

5. Since webhooks are sent in the background, wait a minute and then refresh your Edit Order page to trigger the queued event.

6. Next, open the RequestBin URL and refresh the page. You should see the details of the request that was sent along with the payload data.

Tools for Testing WooCommerce Webhooks

For the example above, I walked you through how to use RequestBin, a popular request collector, which I’ll explain in more detail. I’ll also go over a couple of other useful request collector and testing tools.

1. Request Collector

Request bins (aka request collectors) are designed to help with collecting, inspecting and debugging HTTP requests and webhooks.

RequestBin, which we used above, is one such tool. Others free options include PostBin and Webhook Tester.

Request collectors are great for making sure webhook delivery is working and the payload data is correct. Since these free tools are online service, I recommend only testing webhooks using non-sensitive data.

RequestBin allows you to create a private bin, which will hold up to 20 requests for up to 48 hours. After that time, your requests will no longer be accessible, which is perfect for when you just want a quick or temporary solution for testing webhook delivery.

When a webhook is sent to a request collector URL, you’ll be able to see the request headers and body. But more on this below.

2. WooCommerce Logs

WooCommerce’s logs let you see what a webhook request looks like in terms of headers and data sent, and what was returned from the response. If you’re testing a webhook with a real delivery URL, it’s a good idea to check here to confirm it’s working.

To access webhook logs, go to WooCommerce > Status > Logs and use the dropdown to pick the webhook log you wish to view.

If you don’t have WP_Debug set to true in your wp-config.php file, WooCommerce logs will not display the webhook payload data to avoid logging sensitive order, customer and other post data.

3. Action Scheduler

Since WooCommerce 3.5.0, webhooks are now triggered and sent asynchronously (in the background) using the Action Scheduler.

With the Action Scheduler now bundled into WooCommerce, you can find everything you need to know about the queueing and sending of your webhook events. Just go to Tools > Scheduled Actions to see your data.

Debugging Common WooCommerce Webhook Issues

Once you’ve got your webhook up and running, you might find that at some point you run into issues. There are many causes for webhooks issues, but here are some of the more common ones along with methods you can use to fix them.

Issue #1: Can’t Activate a Webhook

When you activate a newly created webhook, or one that has never been activated before, WooCommerce will immediately test the delivery before allowing it to be activated.

To test the connection, WooCommerce will try to send some data to the delivery URL and if the request doesn’t return a 200 OK response code, the webhook will be given a “Disabled” status.

To help you debug this issue, WooCommerce will display a message with the reason for the error:

• Delivery URL cannot be reached: <reason>
• Delivery URL returned response code: <code>

If the error is related to response codes, here are some common error codes and their meanings:

• 401 – Bad Request: This depends on the delivery URL, but if the webhook is pointing to a third party URL, a 401 typically means the request has invalid data.
• 403 – Forbidden Access: This can mean the request was unauthorized to access the given URL. (Firewall and security plugins can sometimes be the reason for this.)
• 404 – Not Found: The URL doesn’t exist.

Issue #2: Webhook Switches to Disabled After Each Test

WooCommerce will automatically disable any webhooks that respond with an error. To find out exactly what the error was and why it was disabled, the simplest way to find out is to take a look at your WooCommerce logs.

Every WooCommerce webhook delivery is logged (even successful webhooks) along with details of the request and response, which should provide plenty of information to help you work out what went wrong and why.

The log files can get pretty large if you’re running many different webhooks, so searching for webhook IDs or searching for delivery URLs will help find the logs you’re looking for more quickly.

You’re Ready to Start Testing Webhooks

The best way to really understand how webhooks work is to try creating on. Once you’ve got a webhook up and running, you can use the free tools mentioned above—request collectors like RequestBin, WooCommerce logs, and Action Scheduler—to test your webhook and ensure it’s working properly.

For more on developing with WooCommerce, check out our guide: WooCommerce Developer’s Toolbox: 10 Tools We Use at Robot Ninja.

If you have any questions about how webhooks work, or how to test them, leave a question in the comments below!