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

# Webhook subscription object

> The webhook subscription object defines where Mage Loyalty delivers event notifications.

A webhook subscription registers a URL that Mage Loyalty calls whenever one of your selected loyalty events happens. Each subscription has its own signing secret, used to verify that deliveries genuinely came from Mage Loyalty.

## Attributes

| Field         | Type           | Description                                                                                                                                                             |
| ------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`         | string         | The HTTPS endpoint that receives webhook deliveries                                                                                                                     |
| `events`      | string\[]      | The events this subscription is subscribed to. One or more of `points.earned`, `points.redeemed`, `customer.tier_upgrade`, `customer.tier_downgrade`                    |
| `is_active`   | boolean        | Whether deliveries are currently sent to this subscription                                                                                                              |
| `description` | string \| null | Optional label to help you identify the subscription                                                                                                                    |
| `secret`      | string         | The signing secret used to verify delivery signatures. Returned **only** when the subscription is created and when the secret is rotated, never on get, list, or update |
| `created_at`  | string         | ISO 8601 timestamp                                                                                                                                                      |
| `updated_at`  | string         | ISO 8601 timestamp                                                                                                                                                      |

<Warning>
  The `secret` is shown once, at creation and on rotation. Store it securely. If you lose it, [rotate the secret](/api-reference/webhooks/subscriptions/rotate-secret) to get a new one. See [Verifying webhook signatures](/api-reference/webhooks/verifying-signatures) for how the secret is used.
</Warning>

## Example

```json theme={null}
{
  "type": "webhook_subscription",
  "id": "whsub_abc123",
  "attributes": {
    "url": "https://example.com/webhooks/mage",
    "events": ["points.earned", "customer.tier_upgrade"],
    "is_active": true,
    "description": "Production points + tier sync",
    "created_at": "2024-01-01T00:00:00.000Z",
    "updated_at": "2024-01-01T00:00:00.000Z"
  }
}
```