A Webhook is simply an HTTP callback, an HTTP POST that occurs when something happens. Simply put, it is a simple event-notification via HTTP POST. Webhooks allow you to build or set up integrations, which subscribe to certain events on Zinrelo Loyalty Platform. When one of those events is triggered, we'll send an HTTP POST payload to the configured URL. Webhooks are aimed at enabling our merchants to extend the functionality provided by the Zinrelo’s Loyalty program by listening to the events and adding additional functionality like CRM integrations, email notifications and integrations with wallets/account credits etc.

While this document provides a summary of Webhooks, detailed programmer's documentation with examples is also available at Zinrelo Webhooks Slate Documentation.

Events

When configuring a Webhook, you can choose the events you would like to receive payloads for. Subscribing only to the events, which you are going to implement, will help in limiting the HTTP requests to your server. Currently, Zinrelo Loyalty Program supports the following events:-

Event Name

Description

User Enrollment

When a new user enrolls in the loyalty program

Points Awarded

When points are awarded (approved) to a user

Points Redeemed

When a user redeems points

Points Deducted

When points are deducted from user's loyalty points balance

Tier Upgrade

When a customer upgrades to a higher tier

Tier Downgrade

When a customer is downgraded to a lower tier

Points Expired

When customer's points expire.

Coupon Issued to Friend

When a coupon is issued to a friend when they click on a referral link

Coupon Issued to Referrer

When a coupon is issued to the referrer for a successful referral

Configuring your Webhook settings

Webhook settings can be configured in the Notifications section of the Zinrelo store.

Receiving a Webhook notification

Creating a Webhook on your server is simple. Webhook data is sent as JSON in the POST request body. All the details regarding the event are included in the JSON. You are good to go once you parse the JSON.

Example: Let’s consider the following URL:

Webhook URL: http://<your_website.com>/loyalty_webhook/ss_webhook

In case of a Python based webserver, a Webhook can be created the following way:

import json@restrict('POST')
def ss_webhook(self):
try:body = json.loads(request.body)
#handling code based on the event_type provided i.e. body.event_ty
pe
except Exception as e:#handle exceptionThe structure of the response body is as follows:{
"id":Event ID,
"data": Payload,"event_type":Type of Event,
"created":Timestamp}

Based on the event type, the payload will contain the user data or the transaction data. In the case of events: User Enrollment the payload contains the user object. Whereas in case of events: Points Awarded, Points Redeemed, Points Deducted the payload will contain the loyalty transaction details.

Responding to a Webhook

Your endpoint should return 200 HTTP status code to acknowledge receipt of the event. Any code other than the 200 HTTP status code is considered as a failure, and the event will be fired again with 5 minute intervals until the 200 HTTP status code is received or the maximum number of retry attempts has reached (The default retry attempts limit is 5. Get in touch with your Customer Success Manager to configure the settings).

Best Practices

If your Webhook script performs complex logic, or makes network calls, it is possible that the request would timeout before Zinrelo sees the script’s complete execution. For this reason, you may want to have your Webhook endpoint immediately acknowledge receipt by returning a 200 HTTP status code and then perform the rest of its duties.

Webhook endpoints may occasionally receive the same event more than once. We advise you to guard against duplicated event receipts by logging the events you have processed against the Event ID and then not processing already-logged events.

Security

You may want to confirm that the data received at your Webhook URL is actually the data sent by Zinrelo before acting upon it. To do so, you can use the events API endpoint as described below:

Upon receiving a Webhook event follow the below steps:

  1. Parse the JSON data in request body and get the Event ID value.
  2. Use the Event ID value to get the data from Zinrelo using the Events API endpoint.

Events API endpoint

This will get the Event data given the Event ID. The ‘data’ returned in the response of the API is identical to the Event data received via Webhook.

Type of Request: GET

Endpoint: v1/loyalty/events/{id}

Full URL: https://api.zinrelo.com/v1/loyalty/events/{id}

Like the case of any Zinrelo loyalty API endpoint, these keys must be sent in the HTTP header of each API request as follows:

'api-key' : '<your-api-key>'

'partner-id' : '<your-partner-id>'

Example:

curl --header "partner-id: <your-partner-id>" --header "api-key: <your-api-key>" "https://api.zinrelo.com/v1/events/570265a77fae7c14c97a2b63”

The response of the above command is:

JSON

{
"data": {
"id": "570265a77fae7c14c97a2b63",
"data": {
"user_last_name": "Pingle",
"activity_id": "became_an_email_subscriber",
"user_first_name": "Aditya",
"user_id": "56263eac2d6f2a7715b3d2d1",
"order_id": null,"points_status": "approved",
"transaction_type": "award",
"points_expiration_date": null,
"qualified_points": true,"points": 6,
"points_expired": 0,
"created_time": "04-Apr-2016 13:01:27",
"user_email": "aditya@shopsocially.com",
"activity_name": "Became an Email Subscriber",
"merchant_id": "9935740ac1fe23a1962de5cf4250c036",
"id": "570265a7735f835a2ce12a15",
"approved_time": "04-Apr-2016 13:01:27"
},"event_type": "evt_points_awarded",
"created": "04-Apr-2016 13:01:27"
},
"success": true}

Events

When configuring a Webhook, you can choose the events you would like to receive payloads for. Subscribing only to the events, which you implement, will help in limiting the HTTP requests to your server.

The events supported by Zinrelo Loyalty program are:

Event Name

Description

User Enrollment

When a new user enrolls in the loyalty program

Points Awarded

When points are awarded (approved) to a user

Points Redeemed

When a user redeems points

Points Deducted

When points are deducted from user's loyalty points balance

Tier Upgrade

When a customer upgrades to a higher tier

Tier Downgrade

When a customer is downgraded to a lower tier

Points Expired

When customer's points expire.

Coupon Issued to Friend

When a coupon is issued to a friend when they click on a referral link

Coupon Issued to Referrer

When a coupon is issued to the referrer for a successful referral

User Enrollment

User Enrollment event occurs whenever a new user enrolls into Zinrelo loyalty program. The request body for this event contains event type, and payload in the format shown below:

JSON

{"id":,
"data": {
"user_id":,
"user_email":,
"first_name":,
"last_name":,
"gender"•:,
"profile_image_url":,
"redeemed_points":,
"available_points":,
"loyalty_level_id":,"loyalty_lifetime_level_id": ,
"dashboard_url": ,
"expiration_schedule": [],
"last_award_transaction":
"referral_code":
},
"event_type":,
"created":
}

Example request body for a User Enrollment event:

JSON

{
"id": "56ebfcd66ce8864200329b6c",
"data": {
"loyalty_life_time_level_name": "",
"expiration_schedule": [
{
"expiration_date": "18-May-2016 23:59:59",
"points": 100.0
}
],"last_name": "Danielson","redeemed_points": 0,"profile_image_url": "https://grap
h.facebook.com/1702974843251895/picture",
"last_award_transaction": {
"date": "17-Feb-2016 13:14:28",
"points": 100.0,
"name": "Connected via Facebook"
},
"loyalty_level_id": "test2",
"loyalty_lifetime_level_id": "",
"first_name": "Brad",
"user_id": "56c472266ce8862db6721fa0",
"available_points": 0,
"gender": "male","dashboard_url":"https://localhost:8000/loyalty/sample/user/56c472266ce8862db6721fa0/dashboard", "loyalty_level_name": "test2", "awarded_points": 0,"user_email": "brad_danielson@shopsocially.com"
"referral_code" : "TES6177"
},
"event_type": "evt_user_enrollment",
"created": "18-Mar-2016 13:04:21"}

Points Awarded

Points Awarded event occurs whenever any user has been awarded loyalty points. In the case of the activities where moderation is required, the event occurs once the points have been approved. The request body is as shown below:

JSON

{"id": "56fe6d746ce8861e6cc9f84b",
"data":{
"user_id":,
"user_email":,
"user_last_name":,
"user_first_name":,"activity_id":,
"activity_name":,
"id":,
"transaction_type":"award",
"points":,
"points_status":,
"partner_id":,
"created_time":
},
"event_type": "evt_points_awarded","created":}

Example request body for a Points Awarded event:

JSON

{"id": "57026ce2c22f9f7b50bbdf6e",
"data": {
"activity_id": "became_an_email_subscriber",
"user_first_name": "Aditya",
"order_id": null,
"points_status": "approved","points_expired": 0,
"created_time": "04-Apr-2016 13:32:18","merchant_id": "9935740ac1fe23a1962de5cf4250c036",
"id": "57026ce2735f835a2ce12a33",
"approved_time": "04-Apr-2016 13:32:18",
"points_expiration_date": null,
"user_id": "56263eac2d6f2a7715b3d2d1","transaction_type": "award",
"user_last_name": "Pingle",
"points": 300,
"qualified_points": true,"activity_name": "Became an Email Subscriber",
"user_email": "aditya@shopsocially.com"
},
"event_type": "evt_points_awarded","created": "04-Apr-2016 13:32:18"}

Points Redeemed

Points Redeemed event occurs whenever a user redeems his loyalty points. The request body for points redeemed event is described below:

JSON

{
"id": "57010be06ce8862219369c1c",
"data": {
"user_id":,
"user_email":,
"user_last_name":,
"user_first_name":,
"redemption_id":,
"redemption_name":,
"redemption_value":,"id":,
"transaction_type":"redeem",
"points":,
"points_status":"redeemed",
"coupon_code":,
"partner_id":,
"created_time":
},
"event_type": "evt_points_redeemed",
"created":
}}

Example request body for a Points Redeemed event:

JSON

{"id": "570265487fae7c14c77a2b63",
"data": {
"points_status": "redeemed",
"user_id": "56263eac2d6f2a7715b3d2d1",
"redemption_name": "new_redemption 50",
"user_first_name": "Aditya",
"transaction_type": "redeem",
"user_last_name": "Pingle",
"coupon_code": "5",
"points": 1,
"redemption_id": "new_redemption_50","created_time": "04-Apr-2016 12:59:52",
"merchant_id": "9935740ac1fe23a1962de5cf4250c036",
"id": "57026548735f835a2d16b01c",
"user_email": "aditya@shopsocially.com"
},
"event_type": "evt_points_redeemed",
"created": "04-Apr-2016 12:59:52"}

Points Deducted

Points Deducted event occurs whenever points are deducted from a user’s loyalty points balance. The points can be deducted from Zinrelo store or using API calls. The request body for Points Deducted event is as described below:

JSON

{
"id": "57010be06ce8862219369c1c",
"data":{
"user_id":,
"user_email":,
"user_last_name":,"user_first_name":, "id":, "transaction_type":"deduct", "points":, "points_status":"deducted", "available_points":, "partner_id":, "created_time": },"event_type": "evt_points_deducted",
"created": "01-Apr-2016 12:26:08"
}

Example request body of Points Deducted event:

JSON

{
"id": "57026857c22f9f7b50bbdf6c","data": {
"user_first_name": "Aditya",
"user_id": "56263eac2d6f2a7715b3d2d1",
"points_status": "deducted",
"transaction_type": "deduct",
"user_last_name": "Pingle",
"reason": "testing",
"points": 30000,
"points_deducted": 0,
"created_time": "04-Apr-2016 13:12:55",
"merchant_id": "9935740ac1fe23a1962de5cf4250c036",
"id": "57026857735f835a2ce12a27",
"user_email": "aditya@shopsocially.com"
},"event_type": "evt_points_deducted",
"created": "04-Apr-2016 13:12:55"}

Tier Upgrade

The Tier upgrade event occurs whenever a customer earns enough points to move up to a higher tier. The tier upgrade is processed immediately and the webhook is triggered at the time of upgrade. The request body for this event contains event type, and payload in the format shown below:

JSON

{
"id": "57026857c22f9f7b50bbdf6c","data": {
  "first_name": ,
  "last_name":,
  "loyalty_tier_name": ,
  "uid": ,
  "user_id": ,
  "dob": ,
  "loyalty_tier_id": ,
  "available_points": ,
  "redeemed_points": ,
  "awarded_points": ,
  "user_email": ,
  "pending_points":
  }
"event_type": "evt_level_upgrade",
"created": "01-Apr-2016 12:26:08"
}

Example request body for a Tier Upgrade event:

JSON

{"id": "57026857c22f9f7b50bbdf6c","data": {
  "first_name": "Anshuman",
  "last_name": "Zinrelo",
  "loyalty_tier_name": "Pearl",
  "uid": "anshuman",
  "user_id": "5982d90663fda91f6fb37564",
  "dob": "",
  "loyalty_tier_id": "zrl_pearl",
  "available_points": 1738,
  "redeemed_points": 0,
  "awarded_points": 1738,
  "user_email": "anshuman@shopsocially.com",
  "pending_points": 0
  }
"event_type": "evt_level_upgrade",
"created": "01-Apr-2016 12:26:08"
}

Tier Downgrade

The Tier downgrade event occurs whenever a customer is downgraded to a lower tier for not having enough points to stay on the current tier. The tier downgrade criteria is evaluated at the end of a "Tier evaluation period" and also when points are deducted. The example request body for this event contains event type, and payload in the format shown below:

{"id": "57026857c22f9f7b50bbdf6c", "data": {
"last_name": "Zinrelo",
"loyalty_tier_name": "Silver",
"uid": "bob@zinrelo.com",
"loyalty_tier_id": "zrl_silver",
"expired_points": 310,
"referral_code": "YAH9L2YY",
"redeemed_points": 0,
"address_line2": "",
"city": "",
"first_name": "Bob",
"address_line1": "",
"user_id": "5efc47d05920244ad1850e15",
"zipcode": "",
"state": "",
"merchant_id": "5619c3ef8a",
"available_points": 1000,
"pending_points": 0,
"deducted_points": 1010,
"dob": "",
"country": "",
"referral_url": "http://localhost:8000/ref/YAH9L2YY",
"awarded_points": 1310,
"user_email": "bob@zinrelo.com" }
"event_type": "evt_level_degrade",
"created": "01-Apr-2016 12:26:08"
}

Points Expired

The Points expired event occurs whenever loyalty points in a customer's loyalty account balance expire . This event is triggered as soon as the status of the points is marked as expired. The example request body for this event contains event type, and payload in the format shown below:

{"id": "57026857c22f9f7b50bbdf6c", 
"data": {
"points_status": "expired",
"points_expired": 50,
"created_time": "09-Jul-2020 07:11:57",
"id": "5f06c33d5920247cf101614d",
"affiliate_transaction_id": null,
"returned_for_transaction_id": null,
"user_id": "bob@zinrelo.com",
"points_expiration_date": "01-Jan-2020 08:22:43",
"order_id": null,
"customer_qna_question_id": null,
"qualified_points": false,
"activity_id": "f76a3_custom_activity",
"user_first_name": "Bob",
"enroll_acknowledged": false,
"user_lifetime_points_details": {
"total_deducted_points": 110,
"total_earned_points": 790,
"total_expired_points": 230,
"current_available_points": 360,
"total_pending_points": 0,
"total_redeemed_points": 200
},
"merchant_id": "5619c3ef8a",
"approved_time": "09-Jul-2020 07:13:08",
"returned_for_order_id": null,
"transaction_type": "award",
"user_last_name": "Zinrelo",
"points": 50,
"additional_data": {},
"activity_name": "Test activity",
"points_passed": 50,
"user_email": "bob@zinrelo.com"
}
"event_type": "evt_points_expired",
"created": "01-Apr-2016 12:26:08"
}

Coupon Issued to a Friend

The 'Coupon Issued to a Friend' event occurs when a friend clicks on the referral link shared by a user and enters their email to claim a reward. This event is related to the Refer A Friend activity. This event is triggered as soon as the coupon is dispatched to the friend's email address. The example request body for this event contains event type, and payload in the format shown below:

{"id": "57026857c22f9f7b50bbdf6c",
"data": {
"merchant_id": "5619c3ef8a"
"coupon_code": "FRIEND10",
"user_email": "bob@zinrelo.com"
}
"event_type": "evt_coupon_issued_to_friend",
"created": "01-Apr-2016 12:26:08"
}

Coupon Issued to a Referrer

The 'Coupon Issued to a Referrer' event occurs when a successful referral is completed by the friend as a result of which the Referrer gets a coupon as a reward. A successful referral is when the friend clicks on the referral link , claims the reward and makes his first purchase. This event is related to the Refer A Friend activity. This event is triggered as soon as the coupon is dispatched to the referral's email address. The example request body for this event contains event type, and payload in the format shown below:

{"id": "57026857c22f9f7b50bbdf6c", 
"data": {
"last_name": "Test",
"loyalty_tier_name": "",
"uid": "139016",
"loyalty_tier_id": "",
"expired_points": 0,
"created_time": "28-Jul-2020 17:47:58",
"redeemed_points": 0,
"address_line2": "",
"city": "",
"first_name": "Bob",
"address_line1": "",
"user_id": "5f2038c5223d2de73df64c00",
"zipcode": "",
"state": "",
"referral_code": "CAP60A58",
"activity_id": "referral",
"reason": "test",
"merchant_id": "5619c3ef8a",
"available_points": 0,
"pending_points": 0,
"deducted_points": 0,
"dob": "",
"country": "",
"transaction_type": "coupon_award",
"coupon_code": "USCPPG2JLSB",
"referral_url": "http://refer.zinrelo.com/ref/CAP60A58",
"activity_name": "Refer a Friend",
"awarded_points": 0,
"additional_data": {},
"user_email": "bob@zinrelo.com"
}
"event_type": "evt_coupon_issued_to_referrer",
"created": "01-Apr-2016 12:26:08"
}

Did this answer your question?