Stripe

Get your webhook endpoint URL

In the Growth Rail dashboard, open Integrations from the sidebar and select the Stripe tab. It shows your project's Sandbox and Production webhook endpoint URLs, each with a copy button.

Find your unique Stripe webhook URLs inside the Growth Rail Integrations tab.

Create a Stripe webhook

In your Stripe Dashboard, go to Developers → Webhooks and click Add endpoint. Paste the Growth Rail URL from Step 1 and enable exactly these two events:

Repeat this for both sandbox and production Stripe accounts using their respective Growth Rail endpoint URLs.

Copy the Stripe signing secret into Growth Rail

After creating the webhook in Stripe, reveal the Signing secret (whsec_...) on the webhook detail page. Then, in the Growth Rail dashboard, open Integrations from the sidebar, select the Stripe tab, and paste it into the Signing secret field for the matching environment (sandbox or production).

Attach attribution metadata when creating Stripe customers

When your backend creates a Stripe customer for a referred user, include the Growth Rail attribution keys in the metadata object. Retrieve the referral code client-side using the Growth Rail SDK before your signup flow completes, then pass it to your server.

import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

// growthRailUcc comes from the client via getCapturedReferralCode()
async function createStripeCustomer(
  email: string,
  user: { id: string },
  growthRailUcc: string,
  org?: { id: string },
) {
  const customer = await stripe.customers.create({
    email,
    metadata: {
      gr_ucc: growthRailUcc,   // referrer's referral code (required)
      gr_user_id: user.id,     // your user id (required)
      // gr_org_id: org?.id,   // optional, for B2B / org-level referrals
    },
  });

  return customer;
}

On the client side, call getCapturedReferralCode() from the Growth Rail SDK and pass the result to your server when the user signs up:

import { useGrowthRail } from '@growth-rail/react';

export function SignupForm() {
  const { getCapturedReferralCode } = useGrowthRail();

  async function handleSubmit(email: string) {
    const referralCode = getCapturedReferralCode(); // may be null

    await fetch('/api/signup', {
      method: 'POST',
      body: JSON.stringify({ email, referralCode }),
    });
  }

  return (/* your form */);
}