Setting Up Custom Reward Webhooks (API Notifications)

If your e-commerce store is hosted on a custom platform, you can integrate with Stamped Loyalty & Rewards using our API. The addition of "API Notification" settings allows Stamped to notify your platform's server in real time when customers redeem their loyalty points for rewards. Follow this guide to learn more! 

In this guide

• Step 1: Collect your API Credentials
• Step 2: Add your Webhook URL
• Step 3: Code Example & HMAC Verification

Verification header

To help confirm that API notifications are genuinely from Stamped and not spoofed, each notification includes a special security header called x-stamped-signed. This is a SHA-256 encrypted signature created using your Stamped account's ID, API key, and customer ID. You can use your webhook secret along with these values to verify the authenticity of the request and ensure it's coming directly from Stamped.

Step 1: Collect your API Credentials

You will require 4 values to successfully “decrypt” the header to verify the request is from Stamped.

1. Stamped Customer ID
2. Stamped Account ID
3. Public API Key
4. Webhook Secret

You can find these credentials directly in your Stamped Dashboard under Settings > Reward Integrations > API Keys:

• Stamped Account ID: This is your Store Hash.
• Webhook Secret: This is your API Private Key.

Step 2: Add your Webhook URL

• Create your reward in the Stamped dashboard (see our guide linked here for steps)
• In the reward that you've created, scroll to the bottom to find the API Notification section where you can add the desired URL:
  
  

Here's an overview of the process:

1. The customer redeems a reward from the Loyalty launcher
2. Stamped sends the data to the notification URL defined in the rewards settings
3. The merchant receives the data, creates the coupon on their backend, and returns the "id" data (Note: "id" must be returned for the coupon to be created)
4. Stamped displays the coupon in the launcher for redemption

Step 3: Code Example & HMAC Verification

customer_id = "******-****-****-****-*********"
stamped_account_id = "*******-****-****-****-********"
api_key = "******-****-****-****-********" #public api key
webhook_secret = "*******-****-****-******-********"

# Step 1: Create the string that needs to be hashed (StampedAccountId + ApiKey + CustomerId)
string_to_hash = stamped_account_id + api_key + customer_id

# Step 2: Create the HMAC using the secret key and the string to hash
hmac_from_hash = hmac.new(webhook_secret.encode(), string_to_hash.encode(), hashlib.sha256)

# Step 3: Get the hexadecimal representation of the HMAC. Then compare values to verify
hmac_hex = hmac_from_hash.hexdigest()

if hmac_hex == x_stamped_signed_header:
print("Verification successful")
... # Fun code
return jsonify({"id": coupon_id}), 200 #return coupon Id

Success Response

Your endpoint must return a 200 OK status with the following JSON body for the coupon to be displayed to the customer: {"id": "GENERATED_COUPON_CODE"}.