How Rewards Work

The reward system connects three pieces: a trigger event (what the referee does), a tracking record (the referral attribution), and a webhook (how you get notified). When all three align, the reward is granted.

Trigger Event

Referee completes an action

→

Validation

Eligibility checks pass

→

Grant

Status updated to Completed

→

Webhook

Your backend is notified

Trigger Events

A triggerEvent is a string you define — Growth Rail makes no assumptions about what it means. You pass the same string when calling /api/v1/sdk/track-reward-event from your backend server or integration webhook. The event name must match exactly (case-sensitive).

POST /api/v1/sdk/track-reward-event
Header: x-project-secret-key: sk_live_xxx

{
  "newUserId": "user_123",
  "referralTrackingId": "tr_789",
  "eventName": "user_signup",
  "environment": "Production"
}

Common Event Patterns

Event Name	When to Fire	Use Case
`user_signup`	After the referee completes registration	Most common. Simple "refer a friend" programs.
`email_verified`	After the referee verifies their email	Higher quality leads. Reduces fake signups.
`first_purchase`	After the referee makes their first purchase	E-commerce referral programs with revenue requirement.
`plan_upgraded`	After the referee upgrades to a paid plan	SaaS products. Reward only for paying customers.
`kyc_completed`	After identity verification passes	Fintech and regulated industries.
`trial_started`	After the referee starts a free trial	SaaS with trial-based conversion funnels.

Multiple events: You can track multiple reward events for the same referral. For example, grant a small reward on user_signup and a larger one on first_purchase. Each event is tracked independently.

Eligibility Checks

Before granting a reward, Growth Rail performs several checks to ensure the reward is legitimate. All checks must pass for the reward to be granted.

Check	What It Does
Tracking status	The referral tracking item must be in `Pending` status
No duplicate claim	The reward cannot be claimed twice for the same tracking record
Unique referee	The same referee can't be linked to the same referrer more than once
Event match	If the tracking was linked to a specific event, the event name must match

Fraud protection built-in: These checks protect against self-referrals, duplicate accounts, and reward farming. If any check fails, no webhook is fired.

Tracking Reward Events

Server-Side REST API (`/api/v1/sdk/track-reward-event`)

Reward event tracking is performed server-side (or automatically synced via native Stripe and RevenueCat integrations). Send a POST request with your project secret key:

curl -X POST https://api.growthrail.dev/api/v1/sdk/track-reward-event \
  -H "x-project-secret-key: sk_live_your_project_secret" \
  -H "Content-Type: application/json" \
  -d '{
    "newUserId": "user_123",
    "referralTrackingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "eventName": "first_purchase",
    "environment": "Production"
  }'

Reward Delivery

When a reward is granted, Growth Rail fires all enabled webhooks for the campaign. Your backend receives a JSON payload with everything needed to identify and credit the referrer.

For the full webhook payload, authentication, retry behavior, and delivery logs, see the Webhooks guide.

Complete Reward Setup

Here's the end-to-end flow for a referral rewards program:

Configure the campaign

In the dashboard under Campaign Setup, set up the referrer experience (trigger button, modal text) and the new user experience (welcome banner).

Create a webhook

Under Integrations → Reward Webhooks, add your backend endpoint URL and a secret token for verification. See the Webhooks guide for details.

Track the event from your backend

// Call POST /api/v1/sdk/track-reward-event from backend or sync automatically via Stripe/RevenueCat
POST /api/v1/sdk/track-reward-event
{ "newUserId": "user_123", "referralTrackingId": "tr_789", "eventName": "user_signup" }

Handle the webhook in your backend

When the webhook fires, verify the secret and use referrerId and trackingId from the payload to credit your user in your system.