Referral Link Checklist: 20 Checks Before Launch

Before you launch a referral program, check twenty things in five groups: the links, the app build, the claim, the webhook, and your reward rules. Then run the whole path on a real phone with a fresh installer id. Each check below takes a few minutes and names the setting or call that proves it.

Use this as a pass before every release that touches onboarding. The detail behind each check is in the referrals guide and the webhooks guide.

Group 1: Links

1. The link belongs to an app. Only a link with an app can be a referral link. A link with no app answers 400 VALIDATION_ERROR when you turn on is_referral.

2. is_referral is on. Open the link and check Referral link, or read is_referral and referral_since on GET /v1/links/{id}. A tap before referral_since is not a referral.

3. You store the link id with the inviting user. Create the link when a user asks to invite someone and save its id next to that user. When the webhook arrives, link.id tells you whose invitation earned the credit.

4. Every inviter has a link of their own. One link per inviter makes the credit unambiguous. Mint them over REST (POST /v1/links with is_referral: true) or let an assistant do it through MCP create_link.

5. Existing links are converted on purpose. In the links list, select links and choose Make referral links. Filter to referral links with GET /v1/links?is_referral=true and confirm the count.

Group 2: The app build

6. SDK 1.2.0 is in every build you ship. iOS, Android, React Native, and Flutter all read invitations from 1.2.0. Older builds keep working for links and installs but cannot read an invitation.

7. The App Store URL is on the app. The iOS handoff needs it. Without it the request to turn the handoff on answers 409 RECOVERY_PREREQUISITES_MISSING, and details.missing lists app_store_url.

8. An iOS build on 1.2.0 has been opened recently. The dashboard checks for a build on SDK 1.2.0 or later that we have seen in the last 30 days. It does not block the switch: without such a build the dashboard shows a warning, and new iPhone installs from referral links cannot read the invitation and are not credited. Install the release build once and open it.

9. The Android signing fingerprint is registered. Android needs no switch, only a signing fingerprint on the app. The Setup Check id is android_recovery_fingerprint.

10. The iOS handoff switch is on. Under Referral handoff, choose Setup. When the checks are green, turn on Offer referral handoff on iOS. referral_readiness on GET /v1/apps/{id} returns the same answer.

11. The paste button sits on the first screen. Place WarpLinkPasteButton (SwiftUI), WarpLinkUIPasteButton (UIKit), or a field that calls WarpLink.redeemInvitation(text) (React Native and Flutter) where a new person first sees the app. The SDK never reads the clipboard by itself.

12. Skipping the paste step keeps onboarding open. Tap Skip and confirm sign-up still works. Show a referral as applied only when you get a link back.

Group 3: The claim

13. The installer id is a dedicated random id. Use a UUID in its own column. It is opaque, up to 128 characters, and never an email address, a phone number, or other personal data.

14. The claim runs after sign-up. Call claimReferral from the app, or for rewards of value call POST /v1/referrals/claims from your backend with an API key that has referrals:write and an Idempotency-Key header.

15. Every claim status is handled. claimed and flagged are recorded. ignored names the referral that holds the credit in duplicate_of. none is an ordinary answer, not an error.

Group 4: The webhook

16. The endpoint verifies the signature on the raw body. Check X-WarpLink-Signature against an HMAC-SHA256 of ${timestamp}.${rawBody} keyed with the whole whsec_ secret. Reject a timestamp more than 300 seconds old. Compare in constant time. Receivers for Node.js and Python are ready to copy.

17. The endpoint deduplicates by event id. Delivery is at least once. Store the id with the reward and skip an id you have seen.

18. The endpoint answers within 10 seconds. A 2xx marks the event delivered. A 5xx or a timeout retries up to 5 times over 20 minutes. A 4xx or 3xx fails the event, so point the endpoint at its final address.

Group 5: Your rules

19. The credit window matches your offer. Choose 24 hours, 7 days, or 30 days from the tap under Referral handoff. A change applies to taps after you save it.

20. Exact and estimated matches are paid on purpose. Decide what match.exact: false earns, and how referral.updated and referral.flagged events are handled. See exact versus estimated matches.

The phone test

Run this last, on a real phone:

1. Create a referral link and turn on the app's handoff.
2. Delete the app so the tap counts as a first install.
3. Open the link. An iPhone shows the invitation page, then the App Store or a TestFlight build.
4. Install, open the app, and tap the paste button.
5. Sign up as a new test user with a new installer id, and claim.
6. Open Referral handoff, then Referrals, and confirm the new row and the event at your endpoint.
7. Press Send test on the webhook tab to confirm the endpoint answers a signed webhook.test event.

The first valid claim per app and installer id wins, so use a new installer id for each run. Delete a test referral with DELETE /v1/referrals/{id} to start over.

After launch

Open the Referrals report and watch the status column: claimed, delivered, retrying, failed, flagged, duplicate. A failed row means every attempt failed, and you can send it again, with the same event id, for 7 days after its last attempt. Rotate the signing secret from the endpoint menu when a person with access leaves. The old secret keeps signing for 24 hours so you can deploy the new one at your pace.

Frequently Asked Questions

What should I check before launching a referral program?

Check the referral link, the SDK version, the iPhone paste step, the claim, the webhook signature and retries, and your own reward rules. Then run the full path on a real phone with a fresh installer id.

Which SDK version do I need for referrals?

SDK 1.2.0 or later on iOS, Android, React Native, and Flutter. Builds on 1.1.x keep working for links and installs but cannot read an invitation.

How do I test a referral link on my own phone?

Delete the app, open the referral link, install, paste the invitation on iPhone, sign up as a new test user with a new installer id, claim, and confirm the row in the Referrals report and the event at your endpoint.

Do referral links cost extra?

No. Referral links and crediting are included on every plan. Webhook endpoints are limited to 1 per app on Free and 5 per app on paid plans.

How long is the credit window?

You choose 24 hours, 7 days (the default), or 30 days from the tap. A claim inside the window is credited. A later claim is recorded and flagged.

Related Guides

• The iPhone path in detail: Make a referral link survive the App Store install.
• Reward safety: Verify a referral before you grant the reward.
• The release: WarpLink SDK 1.2.0.
• Use cases: App referral programs and invite-friends onboarding.

How WarpLink Helps

We take the infrastructure of a referral program off your list: the invitation link, the install match, the record, and the signed event. The checks above are the few that stay with you, because they describe your app and your rules.

One workflow, three pillars. Deep linking carries the invitation, install attribution credits the link that produced the new user, and real-time analytics shows referrals beside every other link. Sub-10ms redirects on the way in, one SDK on the way out.

Create a free WarpLink account and get deep linking, install attribution, and real-time analytics in one SDK, with 10,000 clicks a month on the free plan.