Webhook Events

Available topics

circle-info

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

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

Topic
Description
Trigger

points/earned

Customer earns points

When points are added to customer account

points/redeemed

Customer redeems points

When points are used to redeem rewards

points/expired

Points expired

When customer's points expire and are deducted

points/about_to_expire_3_days

Points about to expire (3 days)

3 days before points expiration

points/about_to_expire_7_days

Points about to expire (7 days)

7 days before points expiration

points/about_to_expire_30_days

Points about to expire (30 days)

30 days before points expiration

customer/status_changed

Customer status changed

When customer joins, rejoins, or leaves loyalty program

reward/coupon_used

Coupon used

When customer uses a Joy coupon to place an order

tier/upgraded

Customer tier upgraded

When customer is upgraded to a higher tier

tier/downgraded

Customer tier downgraded

When customer is demoted to a lower tier

tier/reset

Tier reset

When customer's tier is reset according to scheduled reset

tier/about_to_reset_4_weeks

Tier about to reset (4 weeks)

4 weeks before tier reset

tier/about_to_reset_2_weeks

Tier about to reset (2 weeks)

2 weeks before tier reset

tier/about_to_reset_1_day

Tier about to reset (1 day)

1 day before tier reset

referral/link_created

Referral link created

When customer creates a referral link for the first time

referral/reward_earned

Referral reward earned

When referrer receives reward after referee completes order

referral/referee_claimed

Referee claimed reward

When referee claims coupon reward

birthday/reward_earned

Birthday reward earned

When customer receives birthday reward

milestone/achieved

Milestone achieved

When customer achieves a milestone

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:

Header Descriptions:

Header
Description

Content-Type

Always set to application/json

X-Joy-Loyalty-Shop-Source-Id

Your shop's unique identifier in Joy system

X-Joy-Loyalty-Hmac-Sha256

HMAC-SHA256 signature for verifying authenticity

X-Joy-Loyalty-Topic

The webhook topic that triggered this request

Base payload structure

All webhook payloads include these common fields:

Event payload examples

Points events

points/earned

points/redeemed

points/expired

points/about_to_expire

Customer events

customer/status_changed

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

Tier events

tier/upgraded

tier/downgraded

Referral events

referral/reward_earned

Birthday events

birthday/reward_earned

Points reward example:

Discount reward example:

Milestone events

milestone/achieved

Last updated