Webhook Details Sent to Delivery URL
Nector sends webhooks to a URL you choose whenever something happens in your loyalty program, for example a customer earns points, gets a coupon or moves to a new VIP tier. Each webhook is an HTTP POST request with a JSON body that carries the details: how many points, which coupon, the customer's new balance, and so on.
This article lists every webhook Nector sends, when it is sent, what each property means, and how to verify and handle the requests.
How webhooks work
1. The request. Nector sends a POST request to your webhook URL. The body is a JSON object with the webhook data. The topic, for example walletreward_create, is in the x-nector-topic header. If you set a webhook prefix in Nector, it is added in front with a dot: a prefix of nector gives nector.walletreward_create.
2. Every webhook has two groups of properties:
- Common properties describe your business and the customer (see Common properties).
- Event specific properties describe the record that triggered the webhook, such as the coupon, order or points reward. They depend on the topic.
3. Nested values stay nested. Extra details are sent inside a meta object, for example meta.lead_name is the customer's name. In this article, nested properties are written with a dot, like meta.coin_reward.
4. Empty values are sent as an empty string "". A top-level value that is missing, null or false arrives as "". A 0 stays 0. Values inside meta are sent as they are, so they can be null, true or false.
5. Amounts can arrive as text. Some amounts are sent as strings, for example "849.54". Convert them to numbers before you do any maths.
6. Links are click-tracked. Links such as the store URL, referral link, coupon link and order link go through Nector's tracking link (https://collectfront.nector.io/track-communication/...). Clicks are counted in your Nector analytics, and the customer is sent on to the real page.
7. Custom properties. Any custom properties you add to the webhook settings in Nector are also included in every webhook.
Request headers
Every webhook request has these headers.
Header | Description | Sample value |
|---|---|---|
| The webhook topic, with your prefix if you set one. |
|
| Signature of the request body, so you can check it came from Nector (see Verifying a webhook). |
|
| Algorithm used for the signature. |
|
| SHA-256 hash of your webhook secret, as hex. |
|
| Algorithm used for the secret hash. |
|
| Unique ID of this delivery attempt. A retry gets a new ID. |
|
| Unix timestamp, in seconds. |
|
| Always |
|
| Always |
|
| Any custom headers you added in Nector. A header named |
|
All webhooks at a glance
Webhooks are split into two groups. Start with the essential ones. Use the others when you need them.
Essential webhooks
These cover the moments most stores act on: points rewarded or redeemed, a new coupon, points about to expire, a referral reward, a review request, a VIP tier change, credits about to expire, an abandoned checkout reminder, and a membership change.
Topic | When it is sent | Properties |
|---|---|---|
| Loyalty points are rewarded to the customer. Can also be triggered when points are redeemed, imported, reverted, adjusted or expired. | |
| A coupon is issued to the customer, for example after redeeming points or as a referral reward. | |
| Reminder: some of the customer's points are about to expire. | |
| Sent to the referrer when the referral is completed and they receive their reward. | |
| Review request, sent after an order so the customer can leave a review. | |
| The customer moves up or down a VIP tier. | |
| Reminder: some of the customer's credits are about to expire. | |
| Reminder: the customer has an abandoned checkout. It may include a recovery coupon. | |
| The customer's paid or VIP membership changes. |
Other webhooks
Topic | When it is sent | Properties |
|---|---|---|
| Reminder: the customer has unused points. | |
| Reminder: the customer has a coupon they haven't used. | |
| A customer submits a product review. | |
| A review is updated, for example approved or featured. | |
| A coupon is updated, for example when it is used. | |
| A new customer is added to your loyalty program. | |
| Anything about the customer changes: their details, points or credit balance, VIP tier, membership and so on. | |
| Credits are rewarded to the customer. Can also be triggered when credits are redeemed, imported, reverted, adjusted or expired. | |
| An order is placed by a customer. | |
| An order changes, for example it is paid, delivered, cancelled or refunded. | |
| A customer asks a product question. | |
| A product question is updated, for example answered. | |
| A VIP tier change record is updated. | |
| A membership change record is updated. | |
| A customer leaves a checkout without paying. | |
| An abandoned checkout is updated. | |
| A referral is created: a friend arrived through a customer's referral link or code. | |
| A referral is updated, for example completed. | |
| Sent to the referred friend when they receive their referral reward. | |
| Reminder to the referred friend, who has not yet completed the referral (has not placed a qualifying order). | |
| A points reward or redemption is updated. | |
| A credit reward or redemption is updated. |
Who is the "customer" in a webhook? The common
user_*properties always describe the customer the webhook is about. In referral webhooks that is the person named in the list above: the referrer or the referred friend.
Common properties sent on every webhook
Business
Property | Description | Sample value |
|---|---|---|
| Your business name, as set in Nector. |
|
| What you call your loyalty points. |
|
| Symbol for your store currency. |
|
| Your store currency. |
|
| Link to your website. | |
| Link to your website that also opens the Nector rewards widget when the page loads. |
Customer
Sent when the webhook is about a customer.
Property | Description | Sample value |
|---|---|---|
| Customer name. |
|
| Customer email. | |
| Mobile number with a leading | |
| Mobile number with the country code and no |
|
| Customer's country code. |
|
| Birthday, as day and month ( |
|
| Full date of birth ( |
|
| Anniversary, as day and month ( |
|
| Full anniversary date ( |
|
|
|
|
| Customer tags synced from your store: lowercase and comma-separated. |
|
| The customer's ID on your store platform, with the platform as a prefix. |
|
| Tags Nector manages for this customer, for example a custom earning rate or a block on referrals. |
|
Loyalty
Property | Description | Sample value |
|---|---|---|
| The customer's current points balance. |
|
| The customer's current points balance. Use |
|
| The customer's current credit balance. |
|
| The customer's current VIP tier. Empty if they have no tier. |
|
| The customer's current membership. Empty if they have none. |
|
| Total amount the customer has saved through your loyalty program. |
|
| Number of friends this customer has referred successfully. |
|
Referral
Property | Description | Sample value |
|---|---|---|
| The customer's own referral code, to share with friends. |
|
| The customer's referral link (recommended). | |
| The older format of the referral link. Use | |
| Despite the name, this is the referral link, the same value as |
Event specific properties
The properties below come in addition to the common properties above. Each record also has its Nector IDs, so you can link webhooks together: for example, the lead_id on an order is the _id of the customer.
Customer webhooks
Topics: lead_create, lead_update
lead_update is sent on every change to the customer or their balances, so it can arrive often. If you only care about some properties, compare them with the values you stored last time.
These properties hold the same values as the matching common properties. For example, email is the same as user_email, available is the same as user_available_balance and tier is the same as user_tier. There are two exceptions:
name: if the customer has no name,user_nameisCustomerwhilenameis empty.mobile: it is the number as stored on the customer's profile, so it may not include the country code, whileuser_mobilealways includes it.
Property | Description | Sample value |
|---|---|---|
| Customer name. |
|
| Customer email. | |
| Customer mobile, as stored. |
|
| Customer's country code. |
|
| Current points balance. |
|
| Current credit balance. |
|
| Current VIP tier. |
|
| Current membership. |
|
| The customer's own referral code. |
|
|
|
|
|
|
|
|
|
|
| Birthday ( |
|
| Anniversary ( |
|
|
|
|
| Customer tags synced from your store. |
|
| The customer's ID on your store platform. |
|
| Whether the email address has been checked: |
|
| Tags Nector manages for this customer. |
|
|
|
|
| The customer's ID in Nector. Other webhooks call it |
|
| Your business ID in Nector. The same on every webhook. |
|
| ID of the customer's points wallet. |
|
| ID of the customer's credit wallet. Empty if credits are not in use. |
|
| SHA-256 hash of the customer's email, as hex. Lets you match customers without sharing the email. |
|
| SHA-256 hash of the customer's mobile number (as stored), as hex. |
|
| When the customer was added to Nector. |
|
| When the customer was last updated. |
|
Points rewarded webhooks
Topics: walletreward_create, wallettransaction_update, unusedwalletcoinrequest_create
These webhooks are sent whenever a customer's points change: mainly when points are rewarded, but also when they are redeemed, imported, reverted, adjusted or expired. Use operation and type to tell them apart. For example, to act only when customers earn points, check for operation = cr and type = reward.
Property | Description | Sample value |
|---|---|---|
| Number of points added or taken away. |
|
|
|
|
| Why the points changed: |
|
| Short description, as shown to the customer. |
|
| Longer description, if any. |
|
| The customer's points balance right after this change. |
|
| Date the points count from. Points expiry is calculated from this date. |
|
| ID of this points transaction. |
|
| Your business ID in Nector. The same on every webhook. |
|
| The customer's ID in Nector (the |
|
| ID of the earning rule. Its name is in |
|
| ID of the Nector activity that created this record, if any. |
|
| What the points are linked to. |
|
| Unique fingerprint Nector uses to block duplicate transactions. |
|
| Name of the earning rule that rewarded these points. |
|
| Fixed identifier of that earning rule. |
|
| Customer name. If the name is missing, a partly hidden email or mobile. |
|
| How many unused-points reminders have been sent for these points. |
|
| When the last unused-points reminder was sent. |
|
| When the points were rewarded (or redeemed, etc.) or last updated. |
|
Credits rewarded webhooks
Topics: creditwalletreward_create, creditwallettransaction_update
Credits work like points but hold a money value. These webhooks are sent whenever a customer's credits change: mainly when credits are rewarded, but also when they are redeemed, imported, reverted, adjusted or expired. Use operation and type to tell them apart. For example, to act only when customers earn credits, check for operation = cr and type = reward. The customer's current credit balance is also in the common property user_available_credit_balance.
Property | Description | Sample value |
|---|---|---|
| Credit amount added or taken away. |
|
|
|
|
| Why the credits changed: |
|
| Short description, as shown to the customer. |
|
| Longer description, if any. |
|
| The customer's credit balance right after this change. |
|
| Date the credits count from. Credit expiry is calculated from this date. |
|
| ID of this credit transaction. |
|
| Your business ID in Nector. The same on every webhook. |
|
| The customer's ID in Nector (the |
|
| ID of the earning rule. Its name is in |
|
| ID of the Nector activity that created this record, if any. |
|
| What the credits are linked to. |
|
| Unique fingerprint Nector uses to block duplicate transactions. |
|
| Name of the earning rule that rewarded these credits. |
|
| Fixed identifier of that earning rule. |
|
| Customer name. If the name is missing, a partly hidden email or mobile. |
|
| When the credits were rewarded (or redeemed, etc.) or last updated. |
|
Coupon webhooks
Topics: coupon_create, coupon_update, unusedcouponrequest_create
Property | Description | Sample value |
|---|---|---|
| The coupon code the customer enters at checkout. |
|
| Coupon name. |
|
| Coupon conditions. |
|
|
|
|
| Size of the discount: a percentage or an amount, depending on |
|
|
|
|
| Minimum cart value needed to use the coupon. Empty if there is no minimum. |
|
| Expiry date and time in a readable format (UTC). |
|
| When the coupon expires. |
|
| Link that opens your store with this coupon already applied. | |
|
|
|
| Number of times the coupon has been used. |
|
| How the coupon was created: |
|
| Platform where the coupon was created. |
|
| ID of this coupon in Nector. |
|
| Your business ID in Nector. The same on every webhook. |
|
| The customer's ID in Nector (the |
|
| ID of the reward in your Nector rewards catalogue that the coupon was redeemed for, if any. |
|
| ID of the earning rule. Its name is in |
|
| ID of the Nector activity that created this record, if any. |
|
| What the coupon is linked to: |
|
| The coupon's ID on your store platform. |
|
| Points the customer spent to get this coupon. |
|
| Credits the customer spent to get this coupon. |
|
|
|
|
|
|
|
|
|
|
|
|
|
| The rule that issued the coupon, for example a referral reward. |
|
| Customer name. |
|
| How many unused-coupon reminders have been sent. |
|
| When the last unused-coupon reminder was sent. |
|
| When the coupon was created or last updated. |
|
Order webhooks
Topics: order_create, order_update
Property | Description | Sample value |
|---|---|---|
| Order number as shown in your store. |
|
| Order total. |
|
| Total discount on the order. |
|
| Tax on the order. |
|
| Order currency. |
|
| Order status: |
|
| Payment status: |
|
| Delivery status: |
|
|
|
|
| Link to the customer's order status page. | |
| If Nector helped bring in this order, how it did so. For example |
|
| Latest order total after any partial refunds. |
|
| Latest discount amount after any changes. |
|
| Payment gateway used. |
|
| Order tags synced from your store. |
|
| UTM parameters from the visit that led to the order. |
|
| Order ID on your store platform. |
|
| Platform the order came from: |
|
|
|
|
| List of products in the order. Each item has |
|
| ID of this order in Nector. |
|
| Your business ID in Nector. The same on every webhook. |
|
| The customer's ID in Nector (the |
|
| Cart token from your store, if any. |
|
| Points the customer earns for this order. |
|
| Points already given for this order. Can be lower than |
|
| Points the customer redeemed on this order. |
|
| Credits the customer redeemed on this order. |
|
| Amount the customer saved on this order through your loyalty program. |
|
| Same as | |
| Customer name. |
|
| Order currency, as sent by your store. |
|
| When the order was completed or delivered. |
|
| When the order was created on your store platform. |
|
| How many review requests have been sent for this order. |
|
| Shipping city. Other shipping details are also sent as |
|
| When the order was added to Nector or last updated. |
|
Order webhooks also contain
discount_lines,note_lines,reward_lines,revert_linesandmeta.order_reward_condition. These are for internal use and you can ignore them.
Review request webhook
Topic: reviewrequest_create
Sent after an order so the customer can review the products they bought. This webhook has the same properties as order webhooks, plus the review link:
Property | Description | Sample value |
|---|---|---|
| Link to the page where the customer can review the products in this order. |
|
Review webhooks
Topics: review_create, review_update
Property | Description | Sample value |
|---|---|---|
| Star rating from 1 to 5. |
|
| Review text. |
|
| Reviewer name, as shown on the review. |
|
| Product name. |
|
| Link to the product page. | |
|
|
|
|
|
|
|
|
|
| Number of photos attached. |
|
| Number of videos attached. |
|
| Your reply to the review, if any. |
|
| Where the review came from: |
|
| Product ID on your store platform. |
|
| Product handle or URL slug. |
|
| Platform the product is from. |
|
| When the review was posted. |
|
| ID of this review in Nector. |
|
| Your business ID in Nector. The same on every webhook. |
|
| The customer's ID in Nector (the |
|
| Nector ID of the order the review is for, if any. |
|
| Points given as a reward for this review, if any. |
|
| Name of the coupon given as a reward for this review, if any. |
|
| When the review was added to Nector or last updated. |
|
Product question webhooks
Topics: qna_create, qna_update
Property | Description | Sample value |
|---|---|---|
| The question. |
|
| Your answer. Empty until answered. |
|
| Name of the person who asked. |
|
| Product name. |
|
| Link to the product page. | |
|
|
|
| Product ID on your store platform. |
|
| Product handle or URL slug. |
|
| Platform the product is from. |
|
| When the question was posted. |
|
| ID of this question in Nector. |
|
| Your business ID in Nector. The same on every webhook. |
|
| The customer's ID in Nector (the |
|
| When the question was added or last updated. |
|
VIP tier webhooks
Topics: viptier_create, viptier_update
Property | Description | Sample value |
|---|---|---|
| The new tier name, formatted for display. |
|
| The customer's new tier (internal name). |
|
|
|
|
| When the customer entered this tier. |
|
| When this tier will expire, if your tiers have an expiry period. |
|
| ID of this tier change in Nector. |
|
| Your business ID in Nector. The same on every webhook. |
|
| The customer's ID in Nector (the |
|
| Customer name. |
|
| When the tier change was recorded or last updated. |
|
Membership webhooks
Topics: vipmembership_create, vipmembership_update
Property | Description | Sample value |
|---|---|---|
| The new membership name, formatted for display. |
|
| The customer's new membership (internal name). |
|
|
|
|
| When the customer got this membership. |
|
| When this membership will expire, if memberships have an expiry period. |
|
| ID of this membership change in Nector. |
|
| Your business ID in Nector. The same on every webhook. |
|
| The customer's ID in Nector (the |
|
| Customer name. |
|
| When the membership change was recorded or last updated. |
|
Abandoned checkout webhooks
Topics: abandonedcheckout_create, abandonedcheckout_update, abandonedcheckoutrequest_create
Property | Description | Sample value |
|---|---|---|
| Link that takes the customer back to their checkout. | |
| Same link, with the recovery coupon (if any) already applied. | |
| Checkout total. |
|
| Cart value before discounts. |
|
| Discount applied. |
|
| Tax. |
|
| Checkout currency. |
|
| List of products in the checkout, in the same format as on orders. |
|
| Contact details entered at checkout. |
|
| When the checkout was completed, if the customer came back and paid. |
|
| ID of this checkout in Nector. |
|
| Your business ID in Nector. The same on every webhook. |
|
| The customer's ID in Nector (the |
|
| Nector ID of the recovery coupon, if one was created. |
|
| The checkout's ID on your store platform. |
|
| The checkout token from your store. |
|
| How many abandoned-checkout reminders have been sent. |
|
|
|
|
| Customer name. |
|
| When the checkout was recorded or last updated. |
|
If a recovery coupon was created for the checkout, the webhook also contains the coupon reward properties (coupon_name, coupon_value and so on).
Referral webhooks
Topics: referral_create, referral_update, refereenotify_create, referrernotify_create, incompletereferralrequest_create
In referral properties, referred_by_* is the referrer (the customer who shared their link or code) and referred_to_* is the referred friend.
Property | Description | Sample value |
|---|---|---|
|
|
|
| Referrer's name. |
|
| Referred friend's name. |
|
| How the friend was referred: |
|
| ID of this referral in Nector. |
|
| Your business ID in Nector. The same on every webhook. |
|
| Referrer's customer ID in Nector. |
|
| Referred friend's customer ID in Nector. |
|
| SHA-256 hashes of the referrer's email and mobile. |
|
| SHA-256 hashes of the friend's email and mobile. |
|
| Nector ID of the friend's order that completed the referral, if any. |
|
| Nector IDs of the coupons given to the referrer and the friend, if the reward was a coupon. |
|
| Nector IDs of the points transactions for the referrer and the friend, if the reward was points. |
|
| Name of the coupon given to the referrer. |
|
| Points given to the referrer (when the referrer's reward is points). |
|
| Name of the coupon given to the referred friend. |
|
| Points given to the referred friend (when the friend's reward is points). |
|
| Value of the friend's order that completed the referral. |
|
| How many incomplete-referral reminders have been sent. |
|
| When the last incomplete-referral reminder was sent. |
|
| When the referral was created or last updated. |
|
Friend's order properties
These are sent when the referral is linked to an order placed by the referred friend.
Property | Description | Sample value |
|---|---|---|
| Order number as shown in your store. |
|
| Order total. |
|
| Discount on the order. |
|
| Tax on the order. |
|
| Order currency. |
|
| Order status (same values as in order webhooks). |
|
| Payment status. |
|
| Delivery status. |
|
| When the order was placed, in a readable format. |
|
| Link to the order status page. |
Reward properties (coupon or points)
These are sent in refereenotify_create, referrernotify_create, incompletereferralrequest_create and abandonedcheckoutrequest_create. They describe the reward the customer received, and only one of the two sets is sent.
If the reward is a coupon:
Property | Description | Sample value |
|---|---|---|
| The coupon code. |
|
| Coupon name. |
|
| Coupon conditions. |
|
|
|
|
| Size of the discount. |
|
|
|
|
| Minimum cart value needed. Empty if there is no minimum. |
|
| Expiry date and time in a readable format (UTC). |
|
| When the coupon expires. |
|
| Link that opens your store with the coupon applied. |
If the reward is points:
Property | Description | Sample value |
|---|---|---|
| Points given. |
|
| Title of the points reward. |
|
| Description, if any. |
|
| Points balance right after the reward. |
|
|
|
|
| Type of points change (see points rewarded webhooks). |
|
Points expiry reminder webhook
Topic: coinexpirynotify_create
Property | Description | Sample value |
|---|---|---|
| Number of points about to expire. |
|
| Date the points expire, in a readable format. |
|
| Approximate date the points expire (reminder date plus one month, week or day). |
|
| How far ahead this reminder is: |
|
| When this reminder was created. |
|
Credit expiry reminder webhook
Topic: creditexpirynotify_create
Property | Description | Sample value |
|---|---|---|
| Credit amount about to expire. |
|
| Date the credits expire, in a readable format. |
|
| Approximate date the credits expire (reminder date plus one month, week or day). |
|
| How far ahead this reminder is: |
|
| When this reminder was created. |
|
Verifying a webhook
You can check that a request really came from Nector in two ways.
Simple check. Hash your webhook secret with SHA-256, as hex, and compare it with the x-nector-webhook-secret header. If they match, the request was sent with your secret.
Signature check. The x-nector-webhook-hmac header is an HMAC-SHA256 signature, as hex, made with your webhook secret. To check it:
- Take the top-level properties of the JSON body and sort them by name.
- Turn them into a URL-encoded query string, the way Node.js
querystring.stringifydoes. - Sign that string with HMAC-SHA256 using your webhook secret, and compare the result with the header.
In Node.js:
const crypto = require("crypto");
const querystring = require("querystring");
function is_valid_nector_webhook(body, hmac_header, webhook_secret) {
const sorted_body = Object.keys(body)
.sort((a, b) => a.localeCompare(b))
.reduce((result, key) => ({ ...result, [key]: body[key] }), {});
const signature = crypto.createHmac("sha256", webhook_secret)
.update(querystring.stringify(sorted_body))
.digest("hex");
return signature === hmac_header;
}
Use the parsed JSON body exactly as you received it. Don't add, remove or change any property before checking.
Responding and retries
- Reply with any 2xx status code within 10 seconds.
- If your server returns an error, or doesn't reply in time, Nector retries twice more: about 1 minute later, then about 2 minutes after that.
- A 401 or 403 reply is not retried.
- Because of retries, you may get the same webhook more than once. The delivery ID changes on every attempt, so to spot duplicates use the record's
_idtogether with the topic andupdated_at.
Updated on: 15/10/2026
Thank you!