> ## Documentation Index
> Fetch the complete documentation index at: https://docs.datalyr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Attribution

> Send real-time purchase events to ad platforms using webhooks from Stripe, Superwall, and RevenueCat

# Webhook Attribution

Connect your payment platform webhooks to automatically send conversion events to Meta, Google, and TikTok Ads. DATALYR uses email-based identity resolution to match purchases back to the original ad click, even when customers complete purchases hours or days later.

## What You'll Learn

* How webhook attribution works
* Difference between webhook attribution and revenue analytics
* Supported platforms and events
* Email-based identity resolution

## How It Works

Webhook attribution connects your payment platform to DATALYR's conversion tracking system. When a customer makes a purchase, DATALYR automatically fires conversion events to your connected ad platforms.

### The Flow

```
1. User clicks ad → DATALYR captures fbclid, gclid, visitor_id
2. User enters email → datalyr.identify(email, { email }) links email to session
3. User purchases → Payment platform sends webhook with email
4. DATALYR queries: "Find visitor_id where user_id = email"
5. DATALYR fires conversion with original attribution to ad platform
```

### Email-Based Identity Resolution

Webhooks only contain purchase data and customer email. DATALYR uses email to find the original ad click attribution stored in your events table.

The system queries Tinybird to find the most recent event where:

* The email matches (via `user_id` or identify traits)
* Attribution data exists (fbclid, gclid, or ttclid)
* Event belongs to your workspace

When a match is found, DATALYR includes the original attribution data (fbclid, gclid, UTM parameters, IP address, user agent) in the conversion event sent to ad platforms.

**Match Rates:**

* 95%+ when email is captured before checkout via `datalyr.identify()`
* 90%+ for cross-device journeys (mobile ad, desktop purchase)
* 85%+ for long sales cycles (30+ day attribution windows)
* 0% if email was never captured with `datalyr.identify()`

## Webhook Attribution vs Revenue Analytics

DATALYR offers two types of integrations for platforms like Stripe:

### Webhook Attribution (This Feature)

**Purpose:** Real-time conversion tracking for ad platforms

**Setup:** Configure webhook URL in payment platform

**Data Flow:** Payment platform → DATALYR → Ad platforms

**What You Get:**

* Automatic conversion events sent to Meta, Google, TikTok
* Email-based attribution matching
* Real-time postback firing
* No OAuth required

**Use Case:** Track purchases and subscriptions as ad conversions

### Revenue Analytics

**Purpose:** Dashboard metrics and business analytics

**Setup:** OAuth connection with API access

**Data Flow:** DATALYR polls API → Tinybird → Dashboard

**What You Get:**

* MRR, ARR, churn rate calculations
* Revenue charts and trends
* Customer lifetime value
* Subscription analytics

**Use Case:** Monitor business health and revenue metrics

## Supported Platforms

<CardGroup cols={3}>
  <Card title="Stripe" icon="stripe" href="/integrations/webhooks/stripe">
    Track checkouts and subscriptions
  </Card>

  <Card title="Superwall" icon="mobile" href="/integrations/superwall">
    Track mobile subscription revenue
  </Card>

  <Card title="RevenueCat" icon="mobile" href="/integrations/revenuecat">
    Track mobile subscription and purchase revenue
  </Card>
</CardGroup>

## Events Created

Each platform creates standardized events that trigger conversion rules:

**Stripe:**

* `purchase` - From checkout.session.completed
* `subscribe` - From customer.subscription.created

**Superwall:**

* `purchase` - From TRANSACTION\_COMPLETE
* `subscribe` - From SUBSCRIPTION\_START

**RevenueCat:**

* `purchase` - From INITIAL\_PURCHASE or NON\_RENEWING\_PURCHASE
* `subscribe` - From RENEWAL

## How Conversion Rules Work

Once webhook events are created with `source: 'stripe'`, `source: 'superwall'`, or `source: 'revenuecat'`, your conversion rules automatically filter by event source.

For example:

* Stripe purchase rule: `event_name = 'purchase' AND source = 'stripe'` → Fires Meta `Purchase`
* Superwall purchase rule: `event_name = 'purchase' AND source = 'superwall'` → Fires Meta `Subscribe`

This prevents cross-platform firing. A Stripe purchase will never trigger a Superwall conversion rule, and vice versa.

## Before You Start

<Check>DATALYR tracking script installed on your website</Check>
<Check>Email capture implemented with `datalyr.identify(email, { email })`</Check>
<Check>Admin access to your payment platform</Check>
<Check>Active workspace in DATALYR</Check>

## Setup Process

1. Navigate to Sources tab in DATALYR dashboard
2. Click "Webhooks" tab
3. Select your payment platform (Stripe, Superwall, or RevenueCat)
4. Copy the webhook URL provided
5. Configure webhook in your payment platform
6. Create conversion rules to fire events to ad platforms

## Attribution Quality

To maximize attribution match rates:

### Capture Email Early

Call `datalyr.identify()` as soon as you have the user's email:

```javascript theme={null}
// When user submits email form
datalyr.identify('customer@example.com', {
  email: 'customer@example.com'
});

// Or after signup
datalyr.identify(user.email, {
  email: user.email,
  name: user.name
});
```

### Verify Tracking

Check that tracking is working before purchase:

1. Visit your site with ad parameters: `yoursite.com?fbclid=test123`
2. Call `datalyr.identify('test@example.com', { email: 'test@example.com' })`
3. Check Event Stream - you should see both events with the same visitor\_id

### Test Webhooks

After configuring webhooks:

1. Make a test purchase with the email you used in step 2
2. Check Event Stream for a `purchase` event with source matching your platform
3. Verify the event has attribution data (fbclid, gclid)
4. Confirm conversion rules fire to ad platforms

## Deduplication

DATALYR automatically deduplicates webhook events using Cloudflare KV storage. Each webhook event ID is checked before processing. Duplicate webhooks (common with retries) are ignored to prevent double-counting conversions.

## Security

Webhooks are verified using signature validation:

* **Stripe:** Verifies `Stripe-Signature` header
* **Superwall:** Verifies webhook signature
* **RevenueCat:** Validates `Authorization` header

Invalid signatures are rejected with 401 Unauthorized.

## Troubleshooting

### No attribution data on webhook events

**Cause:** Email was not captured before purchase

**Solution:** Implement `datalyr.identify(email, { email })` on email capture forms

### Webhook events not appearing

**Cause:** Webhook URL not configured or signature verification failing

**Solution:** Check webhook configuration in payment platform settings

### Conversions firing to wrong platform

**Cause:** Conversion rule not filtering by event source

**Solution:** Edit rule to include `trigger_event_source` filter

## Next Steps

* [Set up Stripe Webhooks](/integrations/webhooks/stripe)
* [Set up Superwall Integration](/integrations/superwall)
* [Set up RevenueCat Integration](/integrations/revenuecat)
* [Create conversion rules](/integrations/conversion-rules)