Getting started
1
Open webhook settings
In your Appstle Memberships admin, go to More → General Settings → Membership Webhook Integration, click Enable Webhook, then click Launch webhook portal.
2
Add an endpoint
In the webhook portal, add an endpoint with your HTTPS URL.
3
Select events
Choose which events you want to receive, or subscribe to all events to ensure you never miss one.
4
Save
Save the endpoint. It starts receiving events immediately.
Webhooks are included in the Enterprise and Enterprise Plus plans. To use them on another plan, contact support@appstle.com.
How webhooks work
Webhooks are HTTPPOST requests sent to your endpoint whenever a membership event occurs. Your endpoint must:
- Be publicly accessible via HTTPS
- Return a
2xxstatus code within the timeout window - Process events asynchronously — queue them for background processing, then respond immediately
Event types
Membership lifecycle events
membership.cancelled and membership.paused fire whenever the status changes, including when Appstle itself cancels or pauses a membership. The member keeps access until Appstle removes the membership’s customer tags: right away or at the end of the paid period, depending on the store’s settings (see Tag lifecycle). membership.expired fires when Appstle removes them. It doesn’t fire when another active membership gives the customer the same tags, or when Appstle removes the tags during payment retries. A paused membership can be activated again afterwards, so don’t treat membership.expired as final.
Failed Payment Recovery is the exception. When it cancels or pauses a membership after its last retry, membership.expired fires once, right away, and can arrive before membership.cancelled or membership.paused. It fires even when another active membership gives the customer the same tags, so check that the customer has no other active membership before you revoke access (see Check whether a customer is an active member). Removing the tags afterwards doesn’t send a second one.
membership.billing-interval-changed fires once for each change of a membership’s billing frequency, wherever the change was made. Appstle sends it when Shopify reports the updated contract, so it can arrive shortly after the call that made the change returns. It doesn’t fire when only the cycle limits change, for a plan switch that keeps the same frequency, or for a change Appstle refuses, such as one that would make billing far more frequent. A plan switch sends membership.updated.
Billing events
Payload structure
All webhooks share this top-level structure:data field contains the event-specific payload.
Membership contract payload
The lifecycle eventsmembership.created, membership.updated, membership.activated, membership.paused, membership.cancelled, membership.expired, membership.swap-product, membership.next-order-date-changed, and membership.billing-interval-changed all deliver a full membership contract object:
null; they’re never left out. Every object in data, data included, also has a __typename field with its Shopify GraphQL type, such as SubscriptionContract or MoneyV2. Where an object can be one of several types, such as customerPaymentMethod.instrument, deliveryMethod or a discount’s value, __typename tells you which one you have. The example shows __typename only there. It also leaves out some nested fields, such as the card’s billingAddress.
Lists hold only their first items: up to 50 lines, 25 discounts and 20 originOrder.fulfillmentOrders. Each of these three has a pageInfo object, and pageInfo.hasNextPage is true when there are more. billingAttempts holds only the latest attempt and has no pageInfo.
Membership contract fields
Billing success payload
billingAttemptResponseMessage from its last failed try, so don’t read that field on membership.billing-success.
Billing failure payload
billingAttemptResponseMessage is a JSON string: Shopify’s report of the failed try, with error_code and error_message among other keys you can ignore. Parse it in a try/catch and handle text you can’t parse as a generic failure.
error_code can arrive in lower or upper case (insufficient_funds or INSUFFICIENT_FUNDS), so trim it and compare in upper case. Match on error_code, never on error_message: that text comes from Shopify and can change.
Node.js
error_code comes from Shopify. It’s usually one of Shopify’s SubscriptionBillingAttemptErrorCode values, such as INSUFFICIENT_FUNDS, EXPIRED_PAYMENT_METHOD, CARD_NUMBER_INCORRECT, AUTHENTICATION_ERROR, PAYMENT_METHOD_DECLINED, FRAUD_SUSPECTED, INVALID_PAYMENT_METHOD or INSUFFICIENT_INVENTORY, and sometimes a more specific decline code. Handle any code you don’t recognize as a generic failure.When billing events fire
membership.billing-failurefires when Shopify reports that a payment try failed. A retry works on the same billing attempt, soidstays the same,attemptCountgoes up andbillingAttemptIdchanges to the new Shopify attempt.retryingNeeded: truemeans Appstle has scheduled another try. Appstle can still drop that try without another event, for example when the membership is paused or cancelled before it runs.retryingNeeded: falsemeans Appstle won’t try this attempt again.- On the last failed try, Appstle also applies the store’s failed-payment action. When it cancels or pauses the membership, you receive
membership.cancelledormembership.paused, plus onemembership.expired. Removing the customer tags afterwards doesn’t send a second one (see Membership lifecycle events). When it skips the order instead, that try’s billing-failure event carriesstatus: SKIPPED_DUNNING_MGMTinstead ofFAILURE. - A failed upgrade payment sends no
membership.billing-failureevent. Appstle rolls the upgrade back instead, which sendsmembership.updatedas the contract returns to the old plan. - A payment that needs the customer’s confirmation (3D Secure) sends no billing event. Appstle marks the attempt
SECURITY_CHALLENGE, emails the customer and pauses the membership. That sendsmembership.paused, thenmembership.expiredwhen Appstle removes the customer tags. When the customer confirms and the payment goes through, you receivemembership.billing-success, andmembership.activatedas Appstle reactivates the membership. - A billing request that Shopify rejects before it tries the payment sends no event for that try.
Billing attempt fields
The samples are trimmed: the payload carries more fields than this table lists, and every field without a value is sent as
null. Ignore fields this table doesn’t describe.
Signature verification
Appstle signs every webhook request. Verify the signature before you process the payload, so you know the request came from Appstle and wasn’t changed in transit. Each request carries three headers, under one of two sets of names. Both sets carry the same values and the same signature, so accept either, as the sample code below does.
Find your webhook signing secret in the webhook portal: go to More → General Settings → Membership Webhook Integration, click Launch webhook portal, and open your endpoint.
To verify a request:
- Use the raw request body exactly as you received it, before any JSON parsing.
- Build the signed content from the message ID header (
webhook-idorsvix-id), a period, the timestamp header (webhook-timestamporsvix-timestamp), a period and the raw body:<id>.<timestamp>.<raw body>. - Take your signing secret, remove its
whsec_prefix and base64-decode the rest. That is the key. - Compute the HMAC-SHA256 of the signed content with that key and base64-encode the result.
- The signature header (
webhook-signatureorsvix-signature) holds one or more space-separated entries in the formv1,<signature>. Accept the request if any entry matches your computed value. Use a constant-time comparison. - Reject the request if the timestamp header is more than five minutes from your server’s clock.
Node.js
Retries
If your endpoint returns a non-2xx status code or times out, Appstle retries the delivery automatically with exponential backoff. You can view delivery history and manually replay events in the webhook portal (More → General Settings → Membership Webhook Integration → Launch webhook portal).
Idempotency
Webhooks can be delivered more than once. Use the message ID header (webhook-id or svix-id) as an idempotency key to skip a delivery you’ve already processed. Record an ID only after you’ve processed its event: if you record it first and processing fails, your check skips the retry and the event is lost.
The message ID identifies one message, so it catches a retried or replayed delivery of that message. Two events are two messages with different IDs, even when they have the same type and membership: a membership that is reactivated and ends again sends a new membership.expired. Make what your handler does safe to repeat as well, for example by revoking access only while it’s still granted.
Local development
Use ngrok to expose your local server for webhook testing:Troubleshooting
Next steps
Admin API integration guide
Look up members, check whether a customer is an active member, and pause, resume or cancel memberships from your server.
Shopify Flow
Tag customers, send emails and update CRMs on lifecycle and billing events.
Authentication
Create API keys, send the
X-API-Key header and handle 401, 403 and 429 responses.API changelog
Dated changes to the Memberships APIs, webhooks, JavaScript events and Flow, with what to do about each.