Webhook events

Event	What it signals	Growth Rail action
`order.paid`	Purchase confirmed by provider.	Record purchase proof; join to pending SDK attribution claim.

How attribution works

A verified provider event proves the purchase happened — but not that the user was referred. Growth Rail completes a referral only when that event joins to the opaque attribution claim previously captured by the SDK on the referring user's device.

Identity rule: Growth Rail joins events to claims using stable IDs and opaque tokens. It never correlates users by email, name, phone number, or billing address.

Create the Growth Rail connection

Open Dashboard → Integrations → Purchases, choose Polar, and create a Sandbox or Production connection. Copy the generated webhook endpoint URL — you will paste it into Polar in the next step.

Register the webhook in Polar

In Polar → Organization settings → Webhooks, add the copied endpoint and subscribe to order.paid.

Return to Growth Rail and save the Polar webhook endpoint secret. Growth Rail encrypts and stores it — the raw value is never returned by the API after saving.

Verification tip: Keep the Polar delivery format set to Raw. Configure an endpoint secret in Polar and save the same value in Growth Rail; the signed webhook ID, timestamp, and exact raw body are validated together.

Security: Never commit webhook secrets to source control or log them. If a secret is compromised, rotate it in both Polar and Growth Rail immediately.

Pass attribution data from your app

For a hosted Checkout Link, append the opaque SDK token as reference_id; Polar propagates it to order metadata. For Checkout API sessions, set metadata.gr_attribution and optionally metadata.gr_user_id plus externalCustomerId.

const checkoutUrl = new URL(polarCheckoutLink);
const attribution = GrowthRail.getAttributionToken();

if (attribution) {
  checkoutUrl.searchParams.set('reference_id', attribution);
}

window.location.assign(checkoutUrl);

Verify end-to-end in test mode

Use the Polar sandbox to complete a positive-value checkout, then confirm one verified order.paid delivery and a Completed or Awaiting attribution outcome in Growth Rail.

Outcome	Meaning
Completed	Purchase proof and SDK attribution token matched. The referral reward has been triggered.
Awaiting attribution	The webhook signature was valid, but the SDK claim has not arrived yet — or the stable user ID did not match a pending claim. The event is held; Growth Rail completes the referral when the claim arrives.
Ignored	The event was verified but no matching attribution claim exists and the hold window has expired, or the event type is out of scope.

Provider-specific notes

Polar also emits order.paid for subscription cycles and changes. Growth Rail requires a still-pending attribution claim and can complete that referral only once; zero-value orders are ignored.
Create separate Polar webhook endpoints and Growth Rail connections for sandbox and production. Live one-time, subscription-start, and trial-conversion fixtures remain release gates.
Refund and chargeback events do not automatically reverse issued rewards in the current version.