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
POSTrequests
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:Request headers
Every webhook request includes these headers: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 request from the dashboard by clicking Test next to any subscription. This is a connectivity check, not one of the subscribable loyalty events: it delivers a payload withevent set to "test" (matching the X-Webhook-Event: test header) and a data object containing a single message field. It is signed with your subscription’s signing secret exactly like a real delivery, so you can use it to confirm your endpoint and signature verification are working before any live events fire.
Managing subscriptions programmatically
You can also create and manage webhook subscriptions through the API instead of the dashboard. See:- List webhook subscriptions
- Create a webhook subscription
- Update a webhook subscription
- Delete a webhook subscription
- Rotate a signing secret