Webhooks are a powerful way to integrate Subi with your external systems, such as custom CRMs, accounting software, email marketing platforms, or automation tools like Zapier.
Whenever a specific subscription event happens in your store, Subi will automatically send a real-time JSON payload to your destination URL.
In this article:
What your store needs
Webhooks are included in every current paid Subi plan and in almost every older one, so most stores do not need an add-on to use them.
On the Free plan, Settings > Webhooks shows a locked screen with an Upgrade your plan button, which lists the plans that include webhooks. If your store is on an older plan and the page still shows a lock, click Upgrade your plan: it offers a current plan that includes it, or the API, webhook & MCP access add-on.
How to create a webhook
Each webhook covers one event type, so create one webhook for each event you want to track. Several webhooks can share the same URL.
To add a new webhook:
Open the Subi app in your Shopify Admin and go to Settings > Webhooks.
Make sure webhooks are turned on. The label next to the Webhooks page title reads Inactive until you click Activate in the top-right corner; it then reads Active and the button changes to Deactivate. While webhooks are inactive, no events are delivered.
In the Registered webhooks card, click Create webhook.
In the modal that appears, select your desired Event from the dropdown menu.
Enter your destination URL (Must be secure and start with
https://).Select the Webhook API version (We recommend always using the Latest version).
Click Save.
📘 Note: Your webhook is active as soon as you save it, provided webhooks are Active on the page (step 2 above).
Supported events
You can subscribe to the following subscription lifecycle events, named as they appear in the Event dropdown:
Subscription Created is sent when a customer starts a new subscription.
Subscription Canceled is sent when a subscription is canceled by the customer or the merchant.
Subscription Paused is sent when an active subscription is paused.
Subscription Resumed is sent when a paused subscription is resumed.
Subscription Billing Succeeded is sent when a renewal payment succeeds.
Subscription Billing Failed is sent when a renewal payment fails (e.g., insufficient funds, expired card).
The reactivation link on the Subscription Canceled event
Every Subscription Canceled payload includes a top-level winback_url field. It is a ready-made link that brings that exact subscription back, so you can drop it straight into your own win-back email or automation without building anything.
Use it when you run your own win-back campaigns from a tool like Klaviyo, Omnisend or a custom CRM, and you want the customer to restart in one click.
What to expect from the link:
It is on every Subscription Canceled payload. In the rare case the link could not be issued, the field is
nullrather than missing, so check for that in your integration before you use it.It opens the subscription at its current price, with no discount attached. Any offer you want to make is yours to add in your own email.
It stays valid for 30 days from the cancellation.
Each cancellation gets its own link. If the same subscription is canceled again later, the newer payload carries a new link and the older one stops working.
Once a customer uses it, it cannot be used a second time.
After 30 days, or once it has been used, the customer sees a short page telling them the link is no longer valid, with a way to log in to their subscriptions instead.
📘 Note: the link does not ask the customer to log in, so treat it like a password. Anyone who has it can restart that subscription and its recurring charges. Send it only to the customer whose subscription it belongs to, and avoid putting it anywhere public.
Testing and managing webhooks
Once created, your webhooks will appear in the Registered webhooks list. To manage a webhook, click the ... icon on the right side of the webhook's row.
From this menu, you can:
Edit: Update the destination URL or change the API version.
Delete: Permanently remove the webhook.
To check that your server receives webhooks, use the Test webhook card: enter an Endpoint URL and click Send test. Subi sends a test event to that URL and confirms with Test webhook sent. Check the delivery logs for the result. The outcome appears in the Recent Deliveries & Logs table below. The Test webhook card is only shown while webhooks are Active. Always test your endpoint during setup to verify your server connection.
Troubleshooting using Logs
If your external system isn't receiving data, you can use Subi's built-in developer logs to find the issue.
Scroll down to the Recent Deliveries & Logs section. This table displays a 30-day history of all webhook attempts.
A green 200 OK badge means your server successfully received the payload.
A red badge (like 500 Error or 404) means there is an issue on your receiving server.
To debug a failed delivery:
Locate the failed event in the log table and click View details.
Go to the Request tab to see the exact JSON payload and headers Subi sent.
Go to the Response tab to see the raw response body returned by your server.
💡 Pro Tip: Analyzing the Response tab is the fastest way for your developers to identify why your endpoint rejected the payload (e.g., formatting errors, authentication blocks, or server downtime).
Sending Subi webhooks to Zapier or Make
We have not built a Subi app for Zapier or for Make, so there is no Subi to search for in their directories. You do not need one, because both tools can receive a webhook directly.
In Zapier, start a Zap with the Webhooks by Zapier trigger and choose Catch Hook. Zapier gives you a URL to copy. Webhooks by Zapier needs a paid Zapier plan, so check that yours includes it. In Make, add the Custom webhook module from Make’s Webhooks app as the first step of a scenario and copy the address it creates.
Back in Subi, open Settings > Webhooks, create a webhook for the event you want and paste that URL as the destination. Each webhook covers one event, so add a webhook for each event you want to automate. Several webhooks can share the same URL.
Zapier and Make learn the shape of your data from the first request they receive. The Test webhook card sends only a short test message with a time, not a subscription, so build your steps on a real event instead. With webhooks Active, pause and then resume a subscription you use for testing, or wait for the next real event of that type, and then map its fields.
Subi’s webhooks name the customer by their Shopify customer ID (customer_id) and do not include their email address. If a later step needs the email, for example to update a contact in your CRM or email tool, look the customer up in Subi first: send a GET request to https://api.subi.co/public/v1.0/subscribers/<customer_id>/ with your API key in the X-Api-Key header, and the answer includes the customer’s email, first name and last name. In Make, use the HTTP app’s Make a request module; in Zapier, a Webhooks by Zapier GET step. See the Subi API guide to create a key.
Recipe: subscription changes as rows in Google Sheets
This keeps one row per subscription change in a Google Sheet, using Make.
In Google Sheets, create a sheet with a header row, for example: Date, Subscription ID, Customer ID, Status, Next billing date, Total, Currency.
In Make, create a scenario that starts with Webhooks > Custom webhook and copy the address.
In Subi, open Settings > Webhooks and create a webhook with that address for each of Subscription Created, Subscription Canceled, Subscription Paused and Subscription Resumed.
With webhooks Active, pause and then resume a subscription you use for testing, so Make receives a real payload.
Add the Google Sheets > Add a Row module and map the columns from
subscription_contract:updated_at,id,customer_id,status,next_billing_date,total_priceandcurrency_code. The status column shows what happened:ACTIVEfor a new or resumed subscription,PAUSEDorCANCELLED.Turn the scenario on.
Recipe: a Slack alert when a renewal payment fails
This posts a message in a Slack channel each time a subscription renewal fails, using Make.
In Make, create a scenario that starts with Webhooks > Custom webhook and copy the address.
In Subi, open Settings > Webhooks and create a webhook for Subscription Billing Failed with that address.
When the first failed renewal arrives, open the scenario and click Run once, so Make reads the fields of the payload.
Add the Slack > Create a Message module, pick your channel and write the text from the payload, for example: Renewal failed for subscription
billing_attempt.subscription_contract.id(customerbilling_attempt.subscription_contract.customer_id):billing_attempt.error_message.Turn the scenario on.
Subi retries a failed payment, so the same subscription can post more than one alert. If the channel gets busy, add a filter on error_code before the Slack step.
Security and payload verification
To ensure the data your server receives is genuinely from Subi and hasn't been tampered with, you must verify the webhook signature.
At the top of the Webhooks page, the Webhook Signing Secret card shows your secret key. Click the copy icon next to it (Copy secret) to copy it to your clipboard.
Subi uses this secret key to generate an HMAC-SHA256 hash of the JSON payload.
This hash is included in the headers of every webhook request under the key:
X-Subi-Hmac-Sha256.
For Developers: Configure your server to compute an HMAC-SHA256 hash of the raw request body using your Secret Key. If your computed hash perfectly matches the value in the X-Subi-Hmac-Sha256 header, the request is verified and safe to process.