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:-

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:

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"
}
Did this answer your question?