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:
How to create a webhook
Subi uses a 1-to-1 webhook model, meaning you need to configure a specific URL for each event type you want to track.
To add a new webhook:
Open the Subi app in your Shopify Admin and go to Settings > Webhooks.
Scroll to the bottom of your configured endpoints list and click the ⊕ Create webhook button.
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 instantly active upon saving and will begin listening for the selected event immediately.
[Tip: Insert a screenshot of the "Add webhook" modal here]
Supported events
You can subscribe to the following subscription lifecycle events:
Subscription created: A customer successfully starts a new subscription.
Subscription canceled: A subscription is canceled by the customer or the merchant.
Subscription paused: An active subscription is temporarily paused.
Subscription re-activated: A paused subscription is resumed.
Successful renewal payment: A recurring billing attempt succeeds.
Failed renewal payment: A recurring billing attempt fails (e.g., insufficient funds, expired card).
Testing and managing webhooks
Once created, your webhooks will appear in the main list. To manage a webhook, click the ... (More actions) icon on the right side of the webhook's row.
From this menu, you can:
Test webhook: Subi will instantly send a mock JSON payload to your URL. A toast notification will pop up confirming if the test was successful. Always test your webhooks during setup to verify your server connection.
Edit: Update the destination URL or change the API version.
Delete: Permanently remove the webhook.
[Tip: Insert a screenshot of the ... menu showing the Test, Edit, and Delete options]
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).
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 your configured webhooks list, look for the text: "Your webhooks will be signed with", followed by a long alphanumeric Secret Key.
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.