Subscription Integration

Prerequisites

This integration requires the WooCommerce Subscriptions plugin to be installed and active on your WooCommerce store. WooCommerce Subscriptions is a paid plugin by Woo that adds subscription functionality, including the “Subscription Created” and “Subscription Updated” webhook topics used in this guide.

Without WooCommerce Subscriptions, these webhook topics will not be available in your WooCommerce settings.

Set WooCommerce Settings

We can create two webhooks for now. One webhook is for creating and another one is for updating.

The first one is “subscription created”. The “subscription created” is called when your customer starts a successful subscription. The second one is “subscription updated”. The “subscription updated” is called when the subscription is renewed and deleted.

First, go to WooCommerce Settings —> Advanced —> Webhooks

Click to “Add webhook” button for Subscription Created Topic

Subscription Created Topic Parameters

• Name: any name you like (e.g. “keyzy-subscription-create”)
• Status: Active
• Topic: Subscription Created
• Delivery URL: https://api.keyzy.io/v2/webhooks/woocommerce-subscription
• Secret: Please follow “Create a New Appkey Pair for Secret” section
• API Version: WP REST API Integration v1

Now, we’ve just created our first webhook for the “subscription created” topic. We need to create another one for “subscription updated”. To do that, click to “Add webhook” button again for the “subscription updated” topic.

Subscription Updated Topic Parameters

• Name: any name you like (e.g. “keyzy-subscription-update”)
• Status: Active
• Topic: Subscription Updated
• Delivery URL: https://api.keyzy.io/v2/webhooks/woocommerce-subscription
• Secret: Please follow “Create a New Appkey Pair for Secret” section
• API Version: WP REST API Integration v1

Create a New Appkey Pair for Secret

• Create a new appkey pair on https://app.keyzy.io/app-keys
• The label should be your base e-commerce base name (e.g. https://www.your-domain.com/)
• Permission: Write
• Is App Key Active?: True
• Copy only API KEY info to WooCommerce’s Secret field
• You only need one API KEY for all webhooks. Create one appkey pair and use the API KEY value for all webhooks.

Bear In Mind

• The product’s SKU number (in WooCommerce, it’s just SKU) and KEYZY’s SKU number should be the same
• Be aware that you need to create a subscription product on WooCommerce.

Troubleshooting

Empty webhook payload

If your webhooks are firing but KEYZY is not receiving any data, the webhook payload body is likely empty. This is a known issue when High-Performance Order Storage (HPOS) is enabled in WooCommerce.

Fix: Go to WooCommerce → Settings → Advanced → Features and enable High-Performance Order Storage compatibility mode. This ensures that subscription webhook payloads are populated correctly.

General tips

• Make sure that the webhook is active or not, if it gets errors, WooCommerce can turn the webhook automatically off.
• There is a lag between the order time and the webhook trigger time. You need to wait for a short time to see the subscription information on KEYZY dashboard.

How to debug

You may need to look at the responses from KEYZY service. To do that, please look at the logs under WooCommerce —> Status —> Logs. You’ll see files starting with webhooks-delivery-YYYY-MM-DD--UNIQUE-ID (e.g. webhooks-delivery-2021-12-05-cf5ea08f2e6045ad6d889249b3ef8fa3.log)