Webhook Configuration

Webhook Configuration

Webhooks allow you to send real-time notifications to external systems when specific events occur in ClickerVolt. This enables powerful integrations with CRMs, email platforms, analytics tools, and custom applications.

This guide covers how to configure webhooks, select trigger events, set up conditional rules, and use the per-condition attribution model for advanced filtering.

Trigger Events

Webhooks can be triggered by specific events in ClickerVolt. Choose which events should fire your webhook:

1. Conversion: Fires when a conversion is recorded (sale, lead, signup)
2. Refund: Fires when a refund is processed (customer request or chargeback)
3. Event Triggered: Fires when any custom event (event1-event10) is triggered

You can enable multiple events for a single webhook. Each enabled event will send a separate HTTP request to your endpoint when it occurs.

Conditional Rules

Conditions allow you to filter which events trigger the webhook. Only events matching all conditions will fire the webhook.

Available condition fields include:

1. UTM parameters: utm_source, utm_medium, utm_campaign, utm_content, utm_term
2. Geographic: country
3. Device info: deviceType
4. Traffic source: referrer, isFromGoogleAds, isFromFacebookAds, isFromTikTokAds
5. Metrics: revenue, qualityScore, conversionCount, eventCount
6. Link filtering: linkId, targetId, eventNumber

Each condition has a field, operator (equals, contains, starts with, etc.), and value. Multiple conditions are combined with AND logic - all must match for the webhook to fire.

Example: To only fire webhooks for Facebook traffic with conversions over $50, add two conditions: "From Facebook Ads equals True" AND "revenue is at least 50".

Per-Condition Attribution

When using UTM parameters or identity fields in conditions, you can choose which click data to use for matching: First Click or Last Click.

What is Attribution?

In multi-touch marketing funnels, a visitor may interact with your campaigns multiple times before converting. The first click captures their initial touchpoint (e.g., a Facebook ad), while the last click captures their most recent touchpoint (e.g., a Google search).

The First/Last Toggle

For UTM and geographic conditions, you'll see a "1st" or "Last" toggle button. This determines which click data is used for that specific condition:

1. First (First Click): Uses data from the visitor's first interaction with your tracking links
2. Last (Last Click): Uses data from their most recent interaction before the event

Mixing Attribution Models

You can mix attribution models within the same rule. For example:

1. "utm_source from First Click equals facebook" - Match visitors who originally came from Facebook
2. "country from Last Click equals US" - But only if their most recent visit was from the US

This flexibility allows sophisticated filtering for complex marketing funnels where you need to consider both the original traffic source and the most recent engagement.

Note: The 1st/Last toggle only appears for fields that support attribution: utm_source, utm_medium, utm_campaign, utm_term, utm_content, country, deviceType, and referrer.

URL Tokens

When configuring your webhook URL, you can use tokens that get replaced with actual values when the webhook fires. Click on a token to insert it at your cursor position.

Available Tokens

1. [revenue] - Conversion revenue amount
2. [transaction] - Transaction ID for the conversion
3. [email] - Visitor email captured on the profile (PII)
4. [ip] - Visitor IP address from the last click
5. [utm_source] - utm_source from the visitor's last click (v1)
6. [utm_medium] - utm_medium from the visitor's last click (v2)
7. [utm_campaign] - utm_campaign from the visitor's last click (v3)
8. [utm_term] - utm_term from the visitor's last click (v4)
9. [utm_content] - utm_content from the visitor's last click (v5)

Example URLs with tokens:

https://api.example.com/track?amount=[revenue]&txn=[transaction]

https://syncmaster.io/subscribe?email=[email]&ip=[ip]&src=olsp-[utm_source]-[utm_medium]

How visitor tokens resolve: [email], [ip], and [utm_*] resolve from the visitor profile attached to the firing event. UTM and IP values come from the visitor's last click (most recent attribution before the event). If a value is missing on the profile, the token is replaced with an empty string so your endpoint URL stays well-formed. All values are URL-encoded automatically.

Testing Webhooks

Before enabling your webhook in production, use the Test button to send a sample request to your endpoint. This helps verify:

1. Your endpoint URL is correct and accessible
2. Your server correctly processes the webhook payload
3. URL tokens are being replaced with sample values

The test will show you the response status code and body from your endpoint. A successful response is typically a 2xx status code.

Best Practices

1. Use HTTPS endpoints for security
2. Implement idempotency - webhooks may be retried on failure
3. Respond quickly (under 5 seconds) to avoid timeouts
4. Log webhook payloads for debugging
5. Use conditions to reduce unnecessary webhook calls
6. Test thoroughly before enabling for production traffic