Skip to main content
Webhooks let your server receive real-time POST requests whenever something happens in your loyalty program — a customer earns points, redeems a reward, or moves between VIP tiers. Instead of polling the API, you register an endpoint URL and choose which events you care about. Mage Loyalty sends a signed JSON payload to your URL within seconds of the event occurring.

​
Requirements

  • A Growth plan or above
  • A publicly accessible HTTPS endpoint that can receive POST requests

​
How it works

1

Create a webhook subscription

In the Mage Loyalty dashboard, go to Settings > Webhooks and create a new subscription. Provide your endpoint URL and select the events you want to receive.
2

Store your signing secret

When you create a subscription, a signing secret is displayed once. Copy and store it securely — you’ll need it to verify that incoming requests are genuinely from Mage Loyalty.
3

Receive and verify

When an event fires, Mage Loyalty sends a POST request to your endpoint. Your server should verify the signature and then process the payload.
4

Return a 2xx

Respond with any 2xx status code to acknowledge receipt. Non-2xx responses are treated as failures and the delivery will be retried up to 3 times.

​
Payload format

Every webhook request has the same top-level structure: 
{
  "event": "points.earned",
  "shop": "my-store",
  "timestamp": "2026-02-18T12:00:00.000Z",
  "data": {
    // Event-specific fields — see individual event pages
  }
}
FieldTypeDescription
eventstringThe event type (e.g. points.earned)
shopstringYour Shopify store identifier
timestampstringISO 8601 timestamp of when the event occurred
dataobjectEvent-specific payload — varies by event type

​
Request headers

Every webhook request includes these headers:
HeaderExampleDescription
X-Webhook-Signaturesha256=a1b2c3...HMAC-SHA256 signature for verification
X-Webhook-Timestamp2026-02-18T12:00:00.000ZTimestamp used in the signing string
X-Webhook-Eventpoints.earnedThe event type
Content-Typeapplication/jsonAlways JSON
User-AgentMageLoyalty-Webhook/1.0Identifies the sender

​
Retries

If your endpoint returns a non-2xx status code or the connection fails, the delivery is retried up to 3 times with exponential backoff.

​
Testing

You can send a test webhook from the dashboard by clicking Test next to any subscription. Test events use the event type test and contain a simple message payload.

​
Available events

EventDescription
points.earnedA customer earned points
points.redeemedA customer redeemed points for a reward
customer.tier_upgradeA customer moved up to a higher VIP tier
customer.tier_downgradeA customer moved down to a lower VIP tier