API Keys & Webhooks
Access your referral data programmatically and receive real-time notifications with API keys and webhooks.
ViralRef provides developer tools for teams that need programmatic access to their referral data or real-time event notifications. These features are available under Settings > Organization > Developers.
API keys are available on paid plans. Webhooks are available on all plans.
API Keys
API keys let you access your ViralRef data from external tools, scripts, or applications.
Creating an API Key
- Go to Settings > Organization > Developers
- Click Create API Key
- Enter a name for the key (e.g., "Zapier Integration" or "Internal Dashboard")
- Click Create
- Copy the key immediately — it will only be shown once
Managing Keys
You can manage your API keys at any time:
- Edit — Rename a key or update its settings
- Revoke — Permanently disable a key. Revoked keys cannot be re-enabled.
Security Best Practices
- Never share API keys in public repositories or client-side code
- Use separate keys for different integrations so you can revoke one without affecting others
- Rotate keys periodically — revoke old ones and create new ones
- Store keys in environment variables, not in code
Webhooks
Webhooks send real-time HTTP notifications to your server when events happen in your ViralRef organization.
Creating a Webhook
- Go to Settings > Organization > Developers
- Click Create Webhook
- Enter the endpoint URL (the URL on your server that will receive events)
- Select the event types you want to receive
- Click Create
Event Types
Webhooks can notify you about:
| Event | When It Fires |
|---|---|
| Conversion created | A new referred purchase is detected |
| Conversion updated | A conversion status changes (approved, rejected, fraud) |
| Affiliate created | A new referrer is added to your program |
| Affiliate updated | An affiliate's status or details change |
| Payout created | A new payout batch is created |
Verifying Webhook Signatures
Each webhook request includes a signature header that you should verify to confirm the request came from ViralRef and wasn't tampered with. The signing secret is shown when you create the webhook.
Webhook Delivery
- Webhooks are sent as HTTP POST requests with a JSON body
- ViralRef expects a 2xx response within 10 seconds
- Failed deliveries are retried with exponential backoff
- You can view delivery history in the webhook settings
Managing Webhooks
- Edit — Change the endpoint URL or event types
- Delete — Remove a webhook and stop receiving events
Common Integration Patterns
Syncing with a CRM
Use webhooks for conversion.created and affiliate.created events to automatically create or update records in your CRM.
Custom Analytics
Use the API to pull conversion and revenue data into your own analytics tools or dashboards.
Automated Workflows
Combine webhooks with tools like Zapier or Make to trigger workflows when new conversions come in (e.g., send a Slack notification, update a spreadsheet).