Webhook API
Webhook Events

Webhook Events

Available topics

ℹ️

Total Events Available: 22 webhook topics covering all major loyalty program interactions

Joy Loyalty supports the following webhook topics for real-time event notifications:

TopicDescriptionTrigger
points/earnedCustomer earns pointsWhen points are added to customer account
points/redeemedCustomer redeems pointsWhen points are used to redeem rewards
points/expiredPoints expiredWhen customer's points expire and are deducted
points/about_to_expire_3_daysPoints about to expire (3 days)3 days before points expiration
points/about_to_expire_7_daysPoints about to expire (7 days)7 days before points expiration
points/about_to_expire_30_daysPoints about to expire (30 days)30 days before points expiration
customer/status_changedCustomer status changedWhen customer joins, rejoins, or leaves loyalty program
reward/coupon_usedCoupon usedWhen customer uses a Joy coupon to place an order
tier/upgradedCustomer tier upgradedWhen customer is upgraded to a higher tier
tier/downgradedCustomer tier downgradedWhen customer is demoted to a lower tier
tier/resetTier resetWhen customer's tier is reset according to scheduled reset
tier/about_to_reset_4_weeksTier about to reset (4 weeks)4 weeks before tier reset
tier/about_to_reset_2_weeksTier about to reset (2 weeks)2 weeks before tier reset
tier/about_to_reset_1_dayTier about to reset (1 day)1 day before tier reset
referral/link_createdReferral link createdWhen customer creates a referral link for the first time
referral/reward_earnedReferral reward earnedWhen referrer receives reward after referee completes order
referral/referee_claimedReferee claimed rewardWhen referee claims coupon reward
birthday/reward_earnedBirthday reward earnedWhen customer receives birthday reward
milestone/achievedMilestone achievedWhen customer achieves a milestone
program/createdProgram createdWhen an earning or spending program is created
program/updatedProgram updatedWhen a public field of an earning or spending program changes
program/deletedProgram deletedWhen an earning or spending program is deleted

Webhook delivery

When a loyalty event occurs, Joy automatically sends a POST request to your registered webhook endpoints with the following characteristics:

  • HTTP Method: POST
  • Content-Type: application/json
  • Timeout: 5 seconds maximum response time
  • Retry Logic: Failed webhooks are retried with exponential backoff
  • Security: All requests include HMAC signature for verification

Request headers

Every webhook request from Joy includes these headers:

Content-Type: application/json
X-Joy-Loyalty-Shop-Source-Id: your_shop_source_id
X-Joy-Loyalty-Hmac-Sha256: signature_hash
X-Joy-Loyalty-Topic: webhook_topic

Header Descriptions:

HeaderDescription
Content-TypeAlways set to application/json
X-Joy-Loyalty-Shop-Source-IdYour shop's unique identifier in Joy system
X-Joy-Loyalty-Hmac-Sha256HMAC-SHA256 signature for verifying authenticity
X-Joy-Loyalty-TopicThe webhook topic that triggered this request

Base payload structure

Customer activity payloads include these common fields (program/* events use a different body, see Program events):

{
  "webhookId": "unique_webhook_id",
  "triggeredAt": "2024-01-15T10:30:00.000Z",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe",
    "shopifyCustomerId": "gid://shopify/Customer/123456"
  },
  "id": "activity_id",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Event payload examples

Points events

points/earned

{
  "topic": "points/earned",
  "shopDomain": "myshop.myshopify.com",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "customerId": "gid://shopify/Customer/123456",
    "email": "[email protected]",
    "points": 100,
    "totalPoints": 1500,
    "source": "order",
    "orderId": "gid://shopify/Order/789"
  }
}

points/redeemed

{
  "topic": "points/redeemed", 
  "shopDomain": "myshop.myshopify.com",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "customerId": "gid://shopify/Customer/123456",
    "email": "[email protected]",
    "pointsRedeemed": 500,
    "remainingPoints": 1000,
    "rewardType": "discount",
    "rewardValue": "$5 OFF"
  }
}

points/expired

{
  "webhookId": "activity_xyz789",
  "triggeredAt": "2024-01-15T10:30:00.000Z",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe", 
    "shopifyCustomerId": "gid://shopify/Customer/123456"
  },
  "id": "activity_xyz789",
  "oldPoint": 500,
  "newPoint": 0,
  "type": "expire_point",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

points/about_to_expire

{
  "webhookId": "about_to_expire_customer123_1705312200000",
  "triggeredAt": "2024-01-15T10:30:00.000Z",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe",
    "shopifyCustomerId": "gid://shopify/Customer/123456"
  },
  "id": "about_to_expire_customer123_1705312200000", 
  "type": "points_about_to_expire",
  "point": 500,
  "expiredAt": "2024-01-22T00:00:00.000Z",
  "daysUntilExpiration": 7,
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Customer events

customer/status_changed

{
  "topic": "customer/status_changed",
  "shopDomain": "myshop.myshopify.com",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "customerId": "gid://shopify/Customer/123456",
    "email": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "type": "user_joined",
    "tier": "Bronze"
  }
}

Possible type values:

  • user_joined: Customer joins loyalty program for the first time
  • user_rejoined: Customer rejoins after leaving
  • user_excluded: Customer is excluded from loyalty program

Reward events

reward/coupon_used

{
  "webhookId": "activity_xyz789",
  "triggeredAt": "2024-01-15T10:30:00.000Z",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe",
    "shopifyCustomerId": "gid://shopify/Customer/123456"
  },
  "id": "activity_xyz789",
  "type": "place_order_with_coupon",
  "couponCode": "JOY-ABC123",
  "orderId": 123456789,
  "orderNumber": 1001,
  "orderName": "#1001",
  "orderSubTotal": "99.99",
  "orderCurrency": "USD",
  "programTitle": "10% Off Discount",
  "redeemPoint": 500,
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Tier events

tier/upgraded

{
  "webhookId": "activity_xyz789",
  "triggeredAt": "2024-01-15T10:30:00.000Z",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe",
    "shopifyCustomerId": "gid://shopify/Customer/123456"
  },
  "id": "activity_xyz789",
  "type": "update_tier",
  "oldTierId": "tier_bronze_123",
  "oldTierName": "Bronze",
  "newTierId": "tier_silver_456", 
  "newTierName": "Silver",
  "tierPoint": 1500,
  "createdAt": "2024-01-15T10:30:00.000Z"
}

tier/downgraded

{
  "webhookId": "activity_xyz789",
  "triggeredAt": "2024-01-15T10:30:00.000Z",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe",
    "shopifyCustomerId": "gid://shopify/Customer/123456"
  },
  "id": "activity_xyz789",
  "type": "demote_tier",
  "oldTierId": "tier_gold_789",
  "oldTierName": "Gold",
  "newTierId": "tier_silver_456",
  "newTierName": "Silver", 
  "tierPoint": 800,
  "reason": "reassessment",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Referral events

referral/link_created

{
  "webhookId": "referral_link_customer123_1705312200000",
  "triggeredAt": "2024-01-15T10:30:00.000Z",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe",
    "shopifyCustomerId": "gid://shopify/Customer/123456"
  },
  "id": "referral_link_customer123_1705312200000",
  "type": "referral_link_created",
  "referralCode": "abc123xyz",
  "urlReferral": "https://myshop.myshopify.com?ref=abc123xyz",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

referral/reward_earned

{
  "webhookId": "referral_reward_customer123_1705312200000",
  "triggeredAt": "2024-01-15T10:30:00.000Z",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe",
    "shopifyCustomerId": "gid://shopify/Customer/123456"
  },
  "id": "referral_reward_customer123_1705312200000",
  "type": "referral_reward_earned",
  "referredCustomerEmail": "[email protected]",
  "rewardType": "point",
  "earnPoints": 500,
  "couponCode": null,
  "orderId": "gid://shopify/Order/789",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Birthday events

birthday/reward_earned

Points reward example:

{
  "webhookId": "birthday_reward_customer123_1705312200000",
  "triggeredAt": "2024-01-15T10:30:00.000Z",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe",
    "shopifyCustomerId": "gid://shopify/Customer/123456"
  },
  "id": "birthday_reward_customer123_1705312200000",
  "type": "earn_point",
  "event": "birthday",
  "source": "user",
  "earnPoints": 100,
  "oldPoint": 500,
  "newPoint": 600,
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Discount reward example:

{
  "webhookId": "5QIhElOglJOCfyX6Zo6I",
  "triggeredAt": "2026-02-06T09:16:33.341Z",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe", 
    "shopifyCustomerId": 9127686570181
  },
  "id": "5QIhElOglJOCfyX6Zo6I",
  "source": "user",
  "event": "birthday", 
  "type": "earn_DISCOUNT",
  "createdAt": "2026-02-06T09:16:33.341Z"
}

Milestone events

milestone/achieved

{
  "webhookId": "activity_xyz789",
  "triggeredAt": "2024-01-15T10:30:00.000Z",
  "customer": {
    "email": "[email protected]",
    "name": "John Doe",
    "shopifyCustomerId": "gid://shopify/Customer/123456"
  },
  "id": "activity_xyz789",
  "type": "earn_point",
  "event": "milestone",
  "earnBy": "order_count",
  "oldPoint": 1000,
  "newPoint": 1100,
  "programTitle": "Order Milestone Rewards",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Program events

Program events tell you when the store's earning or spending programs change, including Mobile app action programs used by the Mobile App Engagement (Custom Actions) API. Tier, referral and other program types do not send them.

TopicSent when
program/createdAn earning or spending program is created (admin, duplicate, or REST POST /programs/earning / /programs/redemption)
program/updatedA public field of the program changes (admin save, bulk enable/disable, REST PUT /programs/{id}). Reordering programs (priority) and internal counters send no event
program/deletedA program is deleted. data is the program as it was before the delete, plus deletedAt

program/updated

{
  "webhookId": "0b9f3c1e-6a43-4c55-9d0e-2f5d1c7a8b10",
  "topic": "program/updated",
  "triggeredAt": "2026-10-30T08:00:00.000Z",
  "data": {
    "id": "9cN2xkq0",
    "type": "earning",
    "event": "custom_program",
    "typeCustom": "custom_action_9cN2xkq0",
    "actionName": "mobile_push_permission_granted",
    "title": "Turn on notifications",
    "status": false,
    "earnPoint": 100,
    "updatedAt": "2026-10-30T07:59:59.000Z"
  }
}
  • data is the REST v2 Program object, the same as GET /rest_api/v2/programs/{id} returns. actionName is present only on Mobile app action programs (typeCustom starting with custom_action_).
  • Delivery is at least once. Answer 2xx within 10 seconds. Any other answer, or none, is retried after 1 min, 10 min, 1 h, 6 h and 16 h (6 attempts over about 23 hours), then dropped. Deduplicate on webhookId. A retry of program/created or program/updated is dropped when the program was deleted or changed again in the meantime, because a newer event carries the newer state.
  • Order is not guaranteed. Keep the latest triggeredAt you processed for each data.id, and ignore an older event.
  • Mobile app actions: on any event whose data.typeCustom starts with custom_action_, call GET /rest_api/v2/custom-actions instead of deriving enabled from the payload, and keep a daily resync: enabled also changes without an event (start/end dates passing, plan changes).