Subscription webhooks and Shopify Flow, wired for the real lifecycle

What Shopify Flow actually is, and where it fits

Shopify Flow is a visual automation builder bundled with Shopify Plus (and now available to non-Plus stores on most plans). You define a trigger, optional conditions, and actions — Flow does the rest. For subscriptions specifically, Flow can listen to subscription-related triggers (some emitted by Shopify directly, some by your subscription app) and execute actions: tag the customer, send an email, post to Slack, update metafields, call an external API, segment in Klaviyo or Mailchimp.

What Flow is good at: simple if-this-then-that lifecycle automations. What Flow is not good at: complex multi-step workflows with branching state, long-running jobs (waits longer than a few minutes), or workflows that require querying multiple APIs and stitching the results. For those, you want a webhook hitting your own backend or a Zapier/Make pipeline. Flow's sweet spot is the 90% of subscription automations that are 'when X happens, do Y' — and that's a lot of automations.

The webhook topics that matter for subscriptions

Shopify and subscription apps emit a stack of webhook topics relevant to the subscriber lifecycle. Not all of them are equally useful — some fire dozens of times per renewal, others only on rare events. Here's the working set most stores actually use.

• subscription_contracts/create — fired when a new subscription contract is created. The signal for 'welcome' automations.
• subscription_contracts/update — fired on any contract change (cadence switch, item swap, payment method update). Noisy; usually filter by what specifically changed.
• subscription_billing_attempts/success — fired when a renewal charge succeeds. The signal for 'order shipped soon' touchpoints.
• subscription_billing_attempts/failure — fired when a renewal charge fails. The single most important webhook for dunning automation.
• subscription_contracts/cancel — fired when a contract is cancelled (voluntary OR involuntary, usually distinguished by reason field).
• orders/create — Shopify-native, fires for every order including subscription renewals. Use the order tag or attributes to detect subscription orders.
• orders/fulfilled — Shopify-native, fires when fulfillment completes. Useful for post-fulfillment touchpoints.
• customers/update — Shopify-native, fires when customer profile changes (e.g. address update). Useful to propagate to your CRM.

The naming differs slightly between apps — some emit their own custom topics like 'subscription/paused' or 'subscription/resumed' that Shopify doesn't natively. Check your specific subscription app's webhook docs. The general principle holds: the lifecycle states (created, billed, billing-failed, cancelled, paused, resumed, updated) all need a webhook hook to be useful.

What a Flow trigger looks like under the hood

When Flow registers a trigger like 'Subscription contract created', it's subscribing to the underlying webhook on your behalf and parsing the payload into Flow's variable system. You don't see the raw JSON in Flow's UI, but it's helpful to understand the shape because it determines what fields you can reference in conditions and actions.

{
  "subscription_contract": {
    "id": 1234567890,
    "customer_id": 987654321,
    "status": "ACTIVE",
    "next_billing_date": "2026-06-15T00:00:00Z",
    "lines": [
      { "product_id": 111, "variant_id": 222, "quantity": 1 }
    ]
  }
}

In Flow, that payload becomes accessible as variables like {{subscriptionContract.id}}, {{subscriptionContract.customer}}, {{subscriptionContract.nextBillingDate}}, and {{subscriptionContract.lines}}. You use those variables in conditions ('if next_billing_date is within 3 days') and in action payloads ('tag this customer with active_subscriber'). The conversion from raw JSON to Flow variables is handled automatically — you only need to know which fields are available.

For raw webhooks (when you're not using Flow), the payload arrives as POST JSON to your endpoint with an HMAC signature in the headers. You verify the signature, parse the body, and act. Most subscription apps document the exact payload shape for each topic — refer to those docs for the canonical schema.

{
  "billing_attempt": {
    "id": 555,
    "subscription_contract_id": 1234567890,
    "status": "FAILED",
    "error_code": "EXPIRED_CARD",
    "error_message": "Card has expired",
    "next_retry_at": "2026-05-25T12:00:00Z",
    "attempts_count": 1
  }
}

The automation patterns that actually save time

Stores that get value from Flow + subscription webhooks tend to run the same five or six patterns. None of them are flashy; all of them either save support time or recover revenue. Build these first.

1. Welcome on contract creation — trigger on subscription_contracts/create, tag the customer 'active_subscriber', send a welcome email with their first delivery date, segment them in your email tool. Saves your CRM from being out of sync.
2. Dunning Slack alert on billing failure — trigger on subscription_billing_attempts/failure, post to a #dunning Slack channel with the customer name, error code, and retry date. Lets support team intervene proactively on high-value subscribers.
3. Pre-renewal reminder for high-value contracts — trigger on subscription_contracts/update or a scheduled Flow checking next_billing_date, if the contract value exceeds your threshold, send the customer a 'your delivery is on the way' email 48 hours before charge.
4. Cancel win-back trigger — trigger on subscription_contracts/cancel, add the customer to a Klaviyo win-back flow (30/60/90 day cadence). Recovers a meaningful single-digit percentage of cancellers.
5. Fulfillment routing by SKU — trigger on subscription_billing_attempts/success, check the line items, if a specific SKU is included, post to your warehouse software's API. Handles edge cases that Shopify's native fulfillment routing can't.
6. Cohort tagging for analytics — trigger on subscription_contracts/create, tag the customer with their signup-month cohort ('cohort_2026_05'). Makes cohort retention analysis possible later in tools that lack native cohorting.

When Flow isn't enough: hybrid patterns

Flow handles 80-90% of subscription automation needs. The remaining 10-20% are workflows that need branching state, multi-step orchestration, or integration with systems Flow doesn't natively support. For those, the pattern is: use Flow as the trigger, have it call your own webhook endpoint, and do the complex logic there.

Concrete example: 'when a billing attempt fails AND the customer's lifetime value exceeds $500, send a personalized email from the founder.' The first part is a Flow condition. The 'lifetime value exceeds $500' check is also possible in Flow (via metafield lookup). But composing the personalized email content — pulling the customer's order history, their preferred products, the right founder signature based on the brand — that's beyond Flow's capability. Solution: Flow triggers on the failure, checks the LTV gate, then calls your endpoint with the customer ID. Your endpoint queries Shopify, composes the email, sends it via your transactional email provider.

• Flow as router — Flow handles the trigger and the simple condition, calls your endpoint for the complex part
• Flow + Zapier/Make — for non-engineering teams, Zapier or Make can sit between Flow's webhook action and external systems, with their own UI
• Direct webhook to your backend — bypass Flow entirely if the automation is purely backend (no Shopify-side actions like tagging)
• Scheduled Flow with custom query — for 'do this every day for subscriptions matching X' patterns, a scheduled Flow with a query step works

Delivery reliability, retries, and idempotency

Webhooks fail. Networks drop, your endpoint hiccups, Shopify's delivery system has occasional latency. Most webhook providers (Shopify included) retry failed deliveries with exponential backoff for up to 48 hours, then give up. That means your webhook consumer needs to be idempotent — the same event might be delivered twice, and your code should produce the same result both times without duplicating side effects.

Concrete example: on subscription_contracts/create, your handler sends a welcome email. If you don't dedupe by event ID or contract ID, a double-delivered webhook means two welcome emails to the same customer — confusing and slightly embarrassing. The fix is to store the event ID (or contract ID + event type) in a database table when you process the event; on receipt, check if you've seen this event already, and skip if so.

• Verify HMAC signature on every webhook — the header is your only proof the request actually came from Shopify
• Dedupe by event ID — store seen event IDs for at least 7 days; skip duplicates
• Respond fast (under 5 seconds) — Shopify treats slow responses as failures and retries. Acknowledge immediately, do the work async if needed.
• Log everything — webhook arrival, processing outcome, errors. Webhook bugs are nearly impossible to debug without logs.
• Test the failure case — what happens if your endpoint is down for an hour? It should still recover when Shopify retries.

Three end-to-end examples

Three concrete automation flows merchants run today. Each is buildable in an afternoon and pays for itself within the first month.

Example 1: VIP subscriber alert. When a subscription contract is created with a total annual value above $500, post to a Slack channel and tag the customer 'vip'. Flow trigger: subscription_contracts/create. Condition: line_items.price × intervals_per_year > 500. Actions: customer tag 'vip', Slack message with customer details. Total build time: 20 minutes. Payback: support team knows to prioritize VIPs proactively.

Example 2: Smart dunning escalation. When a billing attempt fails twice in a row for the same contract, escalate beyond the standard dunning email by adding the customer to a Klaviyo 'high-risk' segment and sending a personal email from support. Flow trigger: subscription_billing_attempts/failure. Condition: attempts_count >= 2. Actions: Klaviyo segment update via webhook, Slack alert. Build time: 1 hour. Payback: recovers an additional 5-10% of involuntary churn vs default dunning.

Example 3: Cancel-reason routing. When a subscription is cancelled with reason 'product quality', tag the customer 'quality_complaint', post to a #quality-alerts Slack channel with the order history, and add them to a 'recover' email flow that includes a quality-control message and a discount on a different product. Flow trigger: subscription_contracts/cancel. Condition: cancel_reason == 'quality'. Actions: customer tag, Slack message, Klaviyo segment. Build time: 45 minutes. Payback: clusters quality complaints so you can spot supplier issues fast, AND recovers some cancellers.

Common pitfalls when wiring subscriptions to Flow

Most automation projects start great and quietly degrade over months as edge cases pile up. The mistakes that cause this are predictable.

• Building automations that no one owns — six months later nobody remembers what 'Flow #7' does and whether it's safe to disable. Document every Flow in a shared doc with purpose, owner, and rollback steps.
• Triggering on /update without filtering — subscription_contracts/update fires on every change, including ones you don't care about. Always filter by the specific field that changed.
• No dead-letter handling — when your endpoint goes down for an hour, Shopify retries for 48 hours then gives up. You need a way to detect and replay the lost events, or you'll silently lose data.
• Ignoring rate limits — high-volume stores can hit Shopify's API rate limit from inside a Flow action (e.g. tagging customers in a loop). Build in throttling or async batching.
• Sending duplicate customer-facing actions — without idempotency a webhook double-delivery sends two emails. The customer notices.
• Hardcoding values that should be configurable — '$500 VIP threshold' should be a metafield, not buried in Flow condition logic. When you want to change it later you'll thank yourself.
• No monitoring on whether automations actually fire — Flow runs silently in the background. Add a periodic 'has Automation X fired in the last 7 days' check or you'll discover months later that it broke.