> ## Documentation Index
> Fetch the complete documentation index at: https://developers.mageloyalty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started with Webhooks

> Receive real-time HTTP notifications when loyalty events happen in your store.

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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Receive and verify">
    When an event fires, Mage Loyalty sends a `POST` request to your endpoint. Your server should [verify the signature](/api-reference/webhooks/verifying-signatures) and then process the payload.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Payload format

Every webhook request has the same top-level structure:

```json theme={null}
{
  "event": "points.earned",
  "shop": "my-store",
  "timestamp": "2026-02-18T12:00:00.000Z",
  "data": {
    // Event-specific fields — see individual event pages
  }
}
```

| Field       | Type   | Description                                   |
| ----------- | ------ | --------------------------------------------- |
| `event`     | string | The event type (e.g. `points.earned`)         |
| `shop`      | string | Your Shopify store identifier                 |
| `timestamp` | string | ISO 8601 timestamp of when the event occurred |
| `data`      | object | Event-specific payload — varies by event type |

## Request headers

Every webhook request includes these headers:

| Header                | Example                    | Description                            |
| --------------------- | -------------------------- | -------------------------------------- |
| `X-Webhook-Signature` | `sha256=a1b2c3...`         | HMAC-SHA256 signature for verification |
| `X-Webhook-Timestamp` | `2026-02-18T12:00:00.000Z` | Timestamp used in the signing string   |
| `X-Webhook-Event`     | `points.earned`            | The event type                         |
| `Content-Type`        | `application/json`         | Always JSON                            |
| `User-Agent`          | `MageLoyalty-Webhook/1.0`  | Identifies 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

| Event                                                                        | Description                               |
| ---------------------------------------------------------------------------- | ----------------------------------------- |
| [`points.earned`](/api-reference/webhooks/points-earned)                     | A customer earned points                  |
| [`points.redeemed`](/api-reference/webhooks/points-redeemed)                 | A customer redeemed points for a reward   |
| [`customer.tier_upgrade`](/api-reference/webhooks/customer-tier-upgrade)     | A customer moved up to a higher VIP tier  |
| [`customer.tier_downgrade`](/api-reference/webhooks/customer-tier-downgrade) | A customer moved down to a lower VIP tier |