Skip to main content

How to set up and manage Webhooks in Subi

Send real-time Subi subscription data to your external tools and servers.

To add a webhook as you read, open Webhooks in Subi.

Would you rather have it prepared for you? Tell us what you want to connect and we prepare it for your store on any paid Subi plan: a Zap, a Make scenario, a Google Sheet or the first lines of code for your developer.

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, the older Free and Essential plans included, so most stores do not need an add-on to use them. The Free plan offered to new stores today does not include them.

If your plan does not include webhooks, Settings > Webhooks shows a locked screen with an Upgrade your plan button, which lists the plans that include them. 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:

  1. Open the Subi app in your Shopify Admin and go to Settings > Webhooks.

  2. Make sure webhooks are turned on. The label next to the Webhooks page title reads Inactive until you open More actions in the top-right corner and click Turn on webhooks; it then reads Active and the same menu offers Turn off webhooks. While webhooks are inactive, no events are delivered.

  3. Click Create webhook in the top-right corner of the page.

  4. In the modal that appears, select your desired Event from the dropdown menu.

  5. Enter your destination URL (Must be secure and start with https://).

  6. Leave Active checked so the webhook starts receiving events.

  7. Click Save.

📘 Note: Your webhook is active as soon as you save it with Active checked, provided webhooks are Active on the page (step 2 above).

📘 Note: You can also create, list and delete webhooks with your Subi API key, for example from your own code. They appear in the Your webhooks card like any other, follow the same rules, and deliver only while webhooks are Active. See the Subi API guide.


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 subscription becomes active again: a paused subscription is resumed, or a canceled one comes back, for example when the customer uses its reactivation link.

  • 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 Subscription Canceled payload also carries a top-level cancellation object saying why the customer canceled: reasons, a list holding the title of each reason they picked, and custom_reason, the words they typed themselves. When the customer did not cancel it themselves, or your store does not ask for a reason, reasons is an empty list and custom_reason is null. When the customer combined two of their subscriptions into one, the object also carries reason_code with the value combined and combined_into_contract_id, the ID of the subscription it was combined into.


The order that started the subscription

All six event payloads, Subscription Created among them, carry a top-level origin_order_id field: Shopify’s numeric ID of the order that created the subscription. Use it to match an event to the original order in your own systems.

It is null rather than missing when no order started the subscription, for example one you created in the Subi admin. On the two billing events it is still the order that started the subscription, not the renewal order that the payment belongs to.


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 null rather than missing, so check for that in your integration before you use it. It is also null when the subscription was canceled because the customer combined it into another one.

  • 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 7 days from the cancellation, the most Shopify allows for a link that works without a login.

  • 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 7 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.


The card-update link on the Subscription Billing Failed event

Every Subscription Billing Failed payload includes a top-level card_update_url field. It is a ready-made link that takes the customer straight to the page where they update the card on that subscription, so you can drop it into your own payment-reminder email or automation without building anything.

Use it when you run your own failed-payment campaigns from a tool like Klaviyo, Omnisend or a custom CRM, and you want the customer to fix their card in one click.

What to expect from the link:

  • It is filled only when the customer pays with Shop Pay, because Shopify only offers a card-update page for Shop Pay. Four more things must hold: the failure is one only a new card fixes, such as an expired card or a wrong card number; Subi's payment recovery is still working on that charge; the subscription is not canceled or expired; and your customer portal lets customers update their payment method. In every other case, a charge declined for insufficient funds included, the field is null rather than missing. Check for that in your integration before you use it.

  • It is on the Subscription Billing Failed payload only. The Subscription Billing Succeeded payload never carries it.

  • It stays valid until the later of 24 hours and the end of the recovery window, never longer than 7 days, and can be opened up to 10 times.

  • Each failed charge gets its own link.

  • Once it expires, 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 update the card on that subscription. 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 appear in the Your webhooks card. Each row shows the event, the destination URL and whether the webhook is Active. Once a server has answered a delivery of that event, the row also says whether the latest one succeeded or failed, for example Last delivery failed · Oct 7, 3:12 PM. That line covers every address registered for the same event, and a delivery that timed out or could not connect does not appear there, so check Recent deliveries for one address's own results. To manage a webhook, click the ... icon on the right side of the webhook's row.

From this menu, you can:

  • Edit: Change the event, the destination URL, or whether the webhook is active.

  • Delete: Permanently remove the webhook.

To check that your server receives webhooks, use Send a test event in the Developer tools card at the bottom of the page: enter an Endpoint URL and click Send test. Subi sends a test event to that URL and waits up to 15 seconds for your server's answer. The result then shows under the field, for example Delivered in 182ms. or 400 Error. Your endpoint rejected the request., and the Recent deliveries card refreshes on its own, with no reload. If your server has not answered by then, Subi shows Test sent. Its result will show in Recent deliveries. The Developer tools card appears once you have created a webhook, and Send a test event 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 card. It lists every delivery attempt, newest first, one row per attempt: the event, a status badge, the destination URL, then the time, the attempt number and the status code your server answered with, for example Oct 7, 3:12 PM · Attempt 6 · Response 400. A delivered row shows no attempt number.

  • A green Delivered badge means your server accepted the delivery. Any status from 200 to 299 counts as accepted.

  • A red Failed badge means your server answered with a status code outside 200 to 299, or could not be reached. When your server answered, the row shows its code, which tells your developers why. Every Failed or Timed out row also ends with a short line saying why, for example Your endpoint rejected the request. or Couldn't connect to example.com.

  • A red Timed out badge means your server did not answer within 10 seconds.

  • A grey Pending badge means the delivery is still on its way.

If Subi tries an event again, each new attempt gets its own row.

To look at one delivery:

  1. Click the ... menu on its row and choose View details.

  2. The Webhook Log Detail window opens with the delivery's own badge, Delivered, Failed, Timed out or Pending. Under Response it shows the status code your server returned, for example 302 Redirect or 400 Error, the line saying why the delivery failed, the Location a redirect pointed to, and the start of the body your server sent back. A delivery that timed out or could not reach your server shows no status code. Below that, Request Headers lists the headers Subi sent with that attempt, X-Subi-Hmac-Sha256 included, and Request Payload shows the payload. The payload there is laid out for reading, so to check a signature use the raw body your server received, not a copy of this one.

Subi keeps the first 1,000 characters of the body your server sent back, which often says why it turned a delivery down. Older deliveries, sent before Subi started keeping it, show the status code only. To see more, look in your server's own logs for that request. Every delivery carries an X-Subi-Webhook-Id header with the same number as the ID at the top of the Webhook Log Detail window, so you can search your server's logs for it.

What the most common failures mean:

  • If your server answers with a 301, 302 or any other 3xx code, the delivery fails, because Subi does not follow redirects. Use the final URL. If the endpoint sits behind a login or an access service such as Cloudflare Access, let requests to that path through without it.

  • If your own signature check answers with a 401 or 403, compare the signature as base64, not hex, and compute it over the raw request body before your code parses it. See Security and payload verification below.

  • A Timed out badge means your endpoint did not answer in time. It has to answer within 10 seconds, so answer with a 200 first and do any slow work after that.

To test your endpoint: in the Developer tools card, under Send a test event, enter your URL and click Send test. Within about 15 seconds the result shows under the field, and Recent deliveries refreshes on its own. A test is sent once and is never retried, while a real event that fails is tried again.


How to send a failed event again

Subi tries each real event six times. If your server still did not accept it, the event is marked as failed, and once you have fixed your server you can send it again from the Webhooks page.

  1. In the Recent deliveries card, find the newest row of the failed event. It shows Failed or Timed out, its attempt number and a Resend button.

  2. Click Resend on that row.

  3. Subi confirms with The event will be sent again within 5 minutes. Reload the page a few minutes later: the new attempt appears at the top of Recent deliveries.

What to expect:

  • Subi sends exactly the same payload and signature as the first time, with the same X-Subi-Event-Id header, so your system can recognise an event it already processed.

  • If the resend fails too, Subi does not retry it on its own. Fix your server and choose Resend again.

  • Resend is only offered on the newest attempt of a failed event. Test events cannot be sent again; send a new test instead. An event whose customer data was erased cannot be sent again either.

  • The event is only sent again to an address that is still registered and active for that event. If you removed the webhook, changed its event or URL, or unchecked Active, Subi shows This address is no longer registered for this topic. Turn the webhook back on, or register the address again if you removed it, then resend.


Sending Subi webhooks to Zapier or Make

Subi has an app on Zapier, added with an invite link: see Connect Subi to Zapier. Zapier checks it for changes every 1 to 15 minutes, depending on your Zapier plan. Make has no Subi app. To get a change the moment it happens, or to use Make, send Subi's webhooks to either tool directly, as below.

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. Send a test event 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.

Do Subi’s webhooks include the customer’s email and name? Yes. Every webhook names the customer by their Shopify customer ID (customer_id) and, right beside it, carries their email address and name: customer_email, customer_first_name and customer_last_name on subscription_contract, or on billing_attempt.subscription_contract for Subscription Billing Succeeded and Subscription Billing Failed. So a later step, for example one that updates a contact in your CRM or email tool, can map the email straight from the payload, with no lookup first. When Subi has no email or name for that customer, the field is there with the value null, so check for that before you use it.

Recipe: subscription changes as rows in Google Sheets

This keeps one row per subscription change in a Google Sheet, using Make.

  1. In Google Sheets, create a sheet with a header row, for example: Date, Subscription ID, Customer ID, Status, Next billing date, Total, Currency.

  2. In Make, create a scenario that starts with Webhooks > Custom webhook and copy the address.

  3. In Subi, open Settings > Webhooks and create a webhook with that address for each of Subscription Created, Subscription Canceled, Subscription Paused and Subscription Resumed.

  4. With webhooks Active, pause and then resume a subscription you use for testing, so Make receives a real payload.

  5. 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_price and currency_code. The status column shows what happened: ACTIVE for a new or resumed subscription, PAUSED or CANCELLED.

  6. 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.

  1. In Make, create a scenario that starts with Webhooks > Custom webhook and copy the address.

  2. In Subi, open Settings > Webhooks and create a webhook for Subscription Billing Failed with that address.

  3. When the first failed renewal arrives, open the scenario and click Run once, so Make reads the fields of the payload.

  4. 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 (customer billing_attempt.subscription_contract.customer_id): billing_attempt.error_message.

  5. 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 bottom of the Webhooks page, the Developer tools card has your key under Signing secret. Click Copy next to it to copy it to your clipboard. Before you have created a webhook, that card is not shown: the key is on the first card instead, under Your webhooks will be signed with, with a copy button beside it.

  • 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, and encode the result as base64, not hex. If it matches the value in the X-Subi-Hmac-Sha256 header, the request is verified and safe to process. A hex digest never matches, so every delivery would be rejected. Code samples are in the webhooks API reference.

Did this answer your question?