Skip to main content
POST
/
v1
/
webhook-subscriptions
curl --request POST \
  --url https://api.mageloyalty.com/v1/webhook-subscriptions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/webhooks/mage",
  "events": ["points.earned", "customer.tier_upgrade"],
  "description": "Production points + tier sync"
}'

{
  "data": {
    "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",
      "secret": "9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  }
}
Register an HTTPS endpoint to receive webhook deliveries for the events you select. Mage Loyalty signs every delivery with the signing secret returned here, so you can verify that requests are genuine.
The secret is returned only in this 201 Created response. It is shown once and never again. Store it securely. If you lose it, rotate the secret to issue a new one. See Verifying webhook signatures for how to use it.

​
Request body

FieldTypeRequiredDescription
urlstringYesThe HTTPS endpoint that will receive deliveries. Must be a valid URL
eventsstring[]YesA non-empty array of events to subscribe to. Valid events: points.earned, points.redeemed, customer.tier_upgrade, customer.tier_downgrade
descriptionstringNoOptional label to help you identify the subscription

​
Response

Returns 201 Created with the new subscription, including the secret.

​
Errors

StatusScenario
400url missing, url not a valid URL, events empty or missing, one or more events invalid, or invalid JSON
401Missing or invalid API key
403The API key is read-only and cannot perform write operations
429Rate limit exceeded (6 requests/second)
curl --request POST \
  --url https://api.mageloyalty.com/v1/webhook-subscriptions \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "https://example.com/webhooks/mage",
  "events": ["points.earned", "customer.tier_upgrade"],
  "description": "Production points + tier sync"
}'

{
  "data": {
    "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",
      "secret": "9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f8a",
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  }
}