Skip to main content
Appstle Loyalty webhooks deliver real-time HTTP POST notifications to your endpoint whenever a loyalty event occurs. Appstle signs every request, retries failed deliveries automatically, and keeps a delivery log you can replay from the webhook portal.
Webhooks are included in the Enterprise and Enterprise Plus plans. To use them on another plan, contact support@appstle.com.

Setting up an endpoint

1

Open webhook settings

In your Appstle Loyalty admin, go to More → Webhook Integration, click Enable Webhook, then click Launch webhook portal.
2

Add an endpoint

In the webhook portal, add an endpoint with your publicly accessible HTTPS URL. Localhost URLs don’t work; see Local development.
3

Choose events

Select the event types you want to subscribe to, or subscribe to all events. The list doesn’t offer loyalty.credits-earned or loyalty.birthday-trigger yet. To receive them, leave every box unticked so the endpoint shows Receiving all events, and ignore the types you don’t handle.
4

Save

Save the endpoint. It starts receiving events immediately.
Your endpoint must return a 2xx status code within the timeout window. Return 200 OK immediately and process the event asynchronously to avoid timeouts under load.

How delivery works

Each webhook is an HTTP POST request with a JSON body. Every delivery comes with:
  • Automatic retries with exponential backoff
  • Unique message IDs for idempotency
  • Signed request headers for verification
  • Delivery logs and manual replay in the webhook portal (More → Webhook Integration → Launch webhook portal)

Event types

When the earned events fire

loyalty.earned and loyalty.credits-earned fire when an earn rule awards a customer points or store credit automatically, such as for an order. They don’t fire for points or store credit added through the Admin API, a Shopify Flow action or a manual adjustment in the Appstle Loyalty admin. Points for reviews, store visits and social media actions don’t send them either. Every award sends one event, by what the earn rule gives: loyalty.earned for points and loyalty.credits-earned for store credit. Both carry the same fields. If your endpoint subscribes to both, each award is delivered once, as the event that matches its reward. The webhook portal doesn’t list loyalty.credits-earned yet, so an endpoint receives it only when it receives all events. The event fires as soon as Appstle saves the award, including when it starts as Pending. An award saved as Rejected sends no event. An award is pending when the earn rule’s When points arrive is set to After a waiting period or After you approve them, or when the Order points arrive setting waits until the order is paid or fulfilled. The event doesn’t fire again when the points are approved. No event type reports the approval either, whether the merchant approves the points, the waiting period ends or the order is paid or fulfilled. The payload carries no transaction ID and no transaction status. Appstle builds customerLoyaltyDetails after it saves the award. In loyalty.earned, the points balances include it: an approved award counts in availablePoints and a pending one in pendingPoints. When one order triggers more than one earn rule, every event’s balances include all of that order’s awards. availablePoints and pendingPoints count points only, so a store credit award never appears in them. In loyalty.credits-earned, storeCreditBalance is the store credit balance Appstle has recorded for the customer. It includes an approved award, but not a pending one. customerEmail is the email Appstle has for the customer, and is left out when it has none. Identify the customer by customerId, which is always there. To find out later whether pending points were approved, read the customer’s point transaction history. Find the newest transaction (by createAt) whose earnRuleId and points match the event’s, then check its status: PENDING, APPROVED or REJECTED. For the customer’s current balances, read their loyalty details, which return pendingPoints and availablePoints.

Referral events

Appstle sends loyalty.referral-reward and loyalty.referred-reward when it gives a customer a reward through the referral program. Each delivery is about the one customer who received the reward. Appstle gives each reward at the step the merchant’s referral program sets: when the friend accepts the invite, creates an account, visits the store or places a qualifying order. The two customers can be rewarded at different times, so expect each event on its own, with its own message ID. When the program rewards the referring customer for every qualifying order, loyalty.referral-reward is sent for each of those orders.
  • customerId and customerEmail belong to the customer who received the reward. customerEmail is empty when that customer has no Appstle record yet, such as a new friend rewarded the moment they accept the invite, and customerLoyaltyDetails is then a short profile, without spentAmount, storeCreditBalance or createAt. Identify the customer by customerId.
  • note describes the reward: the reward’s description for a discount code or store credit, such as Get a $5.00 discount on your entire order with a minimum spend of $0.00, or the earn rule’s customer message for points.
  • customerLoyaltyDetails is the rewarded customer’s profile after the reward. A discount code or store credit reward is already in rewards, with its code in discountCode. Points are already in availablePoints, or in pendingPoints while they’re pending. storeCreditBalance may not include a store credit reward yet.
  • The payload has no points, earnRuleId or redeemRuleId, and it doesn’t say which friend or which order led to the reward.
  • A points reward for the friend’s order or new account also sends loyalty.earned, with the amount in points and the referral’s earn rule in earnRuleId. A points reward given when the friend accepts the invite or visits the store sends only the referral event.
To tie a reward to a referral, read the referring customer’s referral history. It lists each referral’s status and whether each side has been rewarded (referralRewarded and referredRewarded). Friends’ emails are masked there, so it can’t tell you which friend a reward came from.

Payload structure

All events follow the same envelope:

Common payload fields

Every event’s data object includes these fields: A field with no value is left out of the payload instead of being sent as null, at every level. For example, points, earnRuleId and redeemRuleId are missing from the events they don’t apply to, and currentVipTier is missing when the customer has no tier. Points, balances and amounts are decimals and always carry a decimal point, such as 87.0 or 5711.24, so parse them as decimals, not integers.

customerLoyaltyDetails fields

Webhook payloads include additional fields (such as storeCreditBalance, vipTierExpiredAt, rewardedForSharingOnFacebook, and rewardedForSharingOnX) that are not available in the Shopify Flow GraphQL schema. Flow receives a subset of these fields.
Each item in the rewards array contains:

Example payloads

Each example is a real payload, trimmed, with IDs, emails, codes and the store domain replaced.

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

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.

Retries

If your endpoint returns a non-2xx response or times out, Appstle retries the delivery automatically with exponential backoff. View delivery attempts and replay individual events in the webhook portal (More → Webhook Integration → Launch webhook portal).

Local development

Use a tunneling tool such as ngrok to expose your local server during development:

Troubleshooting

Next steps

Admin API integration guide

Manage points, enrollment, referrals, rewards and store credits from your server.

Shopify Flow

Award points, assign VIP tiers and issue store credits without API code.

Authentication

Create API keys, choose Read & write or Read only, and handle 401 and 403 errors.

API changelog

Dated changes to the webhook events, the Loyalty APIs, Flow and Partner Framework, with what to do about each.