RewardsRewards

The Rewards page manages the catalog of rewards users can redeem with points — vouchers, gifts, discount codes. Each reward has name, point cost, quantity (if limited), description. When a user redeems, the system deducts points and can call your webhook to fulfill. Part of Client Admin.

What is a reward?

A reward is something users redeem with accumulated points: vouchers, discount codes, gifts, etc. You define each reward in the catalog (name, point cost, quantity if limited). The user selects a reward and redeems → the Engine deducts points, creates a redemption record, and sends a webhook to your system so you can fulfill (send code, credit account, etc.).

How to use and what are the benefits?

How it works: You create rewards in Client Admin and configure a webhook URL to receive redemption events. Users redeem via the Widget or app; your backend receives the webhook and fulfills. See the flow below for details.

Benefits:

• Turn points into real value: Users see that points can be exchanged for perks/vouchers → more motivation to earn and stay engaged.
• Loyalty & repeat usage: Rewards (discounts, gifts) encourage users to return and buy or use the service again.
• Cost control: You set point price and quantity per reward → control promo budget.

Who uses it (Client Admin)

Used by Client Admin (tenant administrator) after logging in with JWT.

Configuration in Client Admin

Go to Client Admin sidebar → Rewards. Actions: view list, create (name, points, quantity, description), edit, delete. Configure fulfillment webhook in Client Admin or API to receive redemption events. Related: Users, API and Webhook (redemption callback).

Rewards catalog.

Reward flow (overview)

GamifyEngine manages the reward catalog and user points. When a user redeems: the Engine checks sufficient points, tier, inventory → deducts points → creates a redemption record. The actual fulfillment (sending voucher, crediting account, etc.) is done by your system: the Engine sends a webhook to the URL you configure; you receive the payload, fulfill, and (optionally) call a callback to update status.

Redeem reward flow

1. User redeems — In the Widget or your app, the user selects a reward and redeems. The app/Widget calls the redeem API (via SDK or your backend calling the Engine).
2. Engine processes — Validates: user has enough points, correct tier (if reward is tier-restricted), inventory available, cooldown not exceeded. If valid: deduct points, create redemption record (status redeemed), decrease reward quantity if limited.
3. Engine sends webhook — Engine POSTs to your configured webhook URL (Client Admin → Webhook / tenant settings). Payload includes: event: "reward_redeemed", redemption_id, user_id, external_user_id (your system’s user id), reward_id, reward_type, points_spent, reward details. Headers may include X-GamifyEngine-Signature and X-GamifyEngine-Timestamp for verification. You must return 2xx promptly; 4xx/5xx or timeout may trigger retries.
4. Your backend fulfills — Your webhook endpoint receives the JSON body, maps external_user_id and reward, then fulfills (send voucher code, credit account, log, etc.).
5. Callback to update status (optional) — After fulfilling (or on failure), you call the callback API provided by the GamifyEngine operator to update the redemption: mark fulfilled or failed, with timestamp and optional data (e.g. voucher code). Endpoint, body, and API Key details are in the integration doc from the operator or API and Webhook.

flowchart LR
  A["User / App
Redeem"] --> B["GamifyEngine
Deduct points, create redemption"]
  B -->|POST webhook| C["Your backend
Receive payload, fulfill"]
  C -->|2xx OK| B
  C --> D["(Optional) Call callback
fulfilled / failed"]
            

Flow: User redeems → Engine deducts points → sends webhook → You fulfill → (optional) callback.

Callback (webhook you receive)

The Engine sends POST to your webhook URL with a JSON body. Main fields: event = "reward_redeemed", redemption_id (UUID, use when calling the callback API later), external_user_id (your system’s user id, may be null), user_id, reward_id, reward_type, reward_value, points_spent, reward (name, type, fulfillmentData), timestamp. Headers may include X-GamifyEngine-Signature and X-GamifyEngine-Timestamp for verification (HMAC with configured secret). You must return 2xx within the allowed time (e.g. a few seconds) so the Engine considers delivery successful; 4xx/5xx or timeout may trigger retries. After processing (send voucher, credit, etc.), you can call the callback API provided by the operator to update fulfilled_at and status (fulfilled / failed).

Setup webhook

To receive webhooks when users redeem:

1. Prepare an endpoint — Your backend exposes a public URL (HTTPS recommended) that accepts POST, parses JSON, and returns 2xx. It should respond quickly (within seconds) or queue for later processing but still return 2xx immediately.
2. Configure in Client Admin — Log in to Client Admin → go to Webhook settings (or Settings → Webhook). Enter your webhook URL (e.g. https://api.tenant.com/webhooks/gamify-reward). If there is a secret option for signing, set and save it — use this secret on your backend to verify the signature header (HMAC). Save the configuration.
3. Verify signature (recommended) — Each webhook request may include X-GamifyEngine-Signature (HMAC SHA256 of body with secret). Your backend computes HMAC from body + secret and compares with the header to ensure the request is from the Engine.
4. Test — After a test redemption, confirm your endpoint receives the POST with the expected payload; return 2xx and process (or log). If the Engine reports webhook delivery failure, check URL, 2xx response, firewall/SSL.

See also: API and Webhook.