Integration · Developers
Viral Loops + Webhooks & API
Webhooks send new participants, milestones and redeemed rewards to your own endpoint as they happen. The REST API lets your systems add participants, record conversions, redeem rewards and read campaign data.
- What syncs
- 3 webhook events and the REST API
- Plan
- Plus and up
- Setup
- A webhook URL and API token
What syncs between Viral Loops and Webhooks & API?
Send campaign events to your own systems, or build on the REST API.
Viral Loops to Webhooks & API
participation- Someone joins, with their name, email, referral code and who referred them
milestoneReached- A participant reaches a milestone, with the referrals it took and its rewards
rewardRedeemed- A participant's reward is redeemed, with its name and date
Webhooks & API to Viral Loops
Participant Registration- Adds someone to your campaign from your own sign-up flow
Participant Conversion- Records a conversion, with its value if you track one
Redeem a Reward- Redeems a participant's pending reward
Flag Participant- Flags a participant you think is fraudulent
Participant Data- Reads a participant's details, for your own app
Failed webhook deliveries are retried with exponential backoff for up to 4 days, and an endpoint that keeps failing for several days in a row is disabled. API calls with the secret token return full data; the public token returns anonymised data.
What can you do with Webhooks & API and Viral Loops?
- 1
Get every sign-up as it happens
Point the webhook at your endpoint, and each new participant arrives with who referred them, ready for your database or CRM.
- 2
Count a referral when a friend pays
When a referred friend pays, your server sends a conversion with their email and the amount, and the referral counts for whoever invited them.
- 3
Add people from your own sign-up
Call Participant Registration when someone creates an account in your app, and they join your program with their own referral link.
How do you connect Webhooks & API?
Full setup guide- 1
Find your tokens
Your Campaign ID, the public token, and your secret API token are in the campaign's Installation step.
- 2
Add your webhook
In the campaign's Integrations step, choose Webhook and add the URL that should receive the events.
- 3
Test the payloads
Point the webhook at a webhook.site address first to see what each event sends, then switch to your own endpoint.
- 4
Call the API from your server
Keep the secret token server-side. The endpoints are documented at developers.viral-loops.com.
Which templates work best with Webhooks & API?
All templates
Referral templateThe Universal Referral
Referral templateThe Milestone ReferralFAQ
Webhooks & API FAQ
Which webhook events does Viral Loops send?
participation when someone joins, milestoneReached when a participant reaches a milestone, and rewardRedeemed when a reward is redeemed. Each one includes the participant's details.
What happens if my endpoint is down?
Failed deliveries are retried with exponential backoff for up to 4 days. An endpoint that fails for several days in a row is disabled.
Which token should I use?
The secret API token for server-side calls: it returns full data, so never put it in the browser. The public token, your Campaign ID, works for some calls and returns anonymised data.
Do I need the API to track conversions?
No. You can also track them with the JavaScript SDK, by page visit or with Stripe. The API is for tracking them from your server.
Can I check that a webhook came from Viral Loops?
Yes. Webhook signature verification is included from Plus, and IP-restricted webhook access from Growing.
Which plan includes webhooks and the API?
Plus, Growing and Power. The JavaScript SDK is on every plan, including Start-up.
Connect Webhooks & API to your referral program.
Plans start at $35 a month, billed annually. Try it free for 14 days, or talk to our team.