Skip to main content
Appstle Memberships webhooks deliver real-time HTTP notifications to your server whenever a membership event occurs. Appstle signs every request, retries failed deliveries automatically, and keeps a delivery log you can replay from the webhook portal.

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 HTTP POST requests sent to your endpoint whenever a membership event occurs. Your endpoint must:
  • Be publicly accessible via HTTPS
  • Return a 2xx status 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:
The data field contains the event-specific payload.

Membership contract payload

The lifecycle events membership.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:
Fields with no value arrive as 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

A billing attempt that succeeds after a retry keeps 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-failure fires when Shopify reports that a payment try failed. A retry works on the same billing attempt, so id stays the same, attemptCount goes up and billingAttemptId changes to the new Shopify attempt. retryingNeeded: true means 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: false means 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.cancelled or membership.paused, plus one membership.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 carries status: SKIPPED_DUNNING_MGMT instead of FAILURE.
  • A failed upgrade payment sends no membership.billing-failure event. Appstle rolls the upgrade back instead, which sends membership.updated as 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 sends membership.paused, then membership.expired when Appstle removes the customer tags. When the customer confirms and the payment goes through, you receive membership.billing-success, and membership.activated as 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:
  1. Use the raw request body exactly as you received it, before any JSON parsing.
  2. Build the signed content from the message ID header (webhook-id or svix-id), a period, the timestamp header (webhook-timestamp or svix-timestamp), a period and the raw body: <id>.<timestamp>.<raw body>.
  3. Take your signing secret, remove its whsec_ prefix and base64-decode the rest. That is the key.
  4. Compute the HMAC-SHA256 of the signed content with that key and base64-encode the result.
  5. The signature header (webhook-signature or svix-signature) holds one or more space-separated entries in the form v1,<signature>. Accept the request if any entry matches your computed value. Use a constant-time comparison.
  6. Reject the request if the timestamp header is more than five minutes from your server’s clock.
Node.js
Pass the raw request body to the verification function, before JSON parsing. Parsing the body and serializing it again can change its bytes (for example 15.0 becomes 15), and a correct signature then fails to verify. In Express, use express.raw() on the webhook route, and register that route before any app-wide express.json(), which would otherwise parse the body first.

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.