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.

​

Stripe Webhooks

​

What You’ll Learn

• How to configure Stripe webhooks
• Supported Stripe events
• Email attribution matching
• Testing and verification

​

Before You Start

• DATALYR tracking script installed on your website
• Email capture with datalyr.identify({ email }) before checkout
• Admin access to Stripe Dashboard
• Active workspace in DATALYR

​

Supported Events

​

How Attribution Works

1. Stripe sends webhook with customer_email to DATALYR
2. DATALYR queries events table: “Find visitor_id where email matches”
3. DATALYR retrieves original attribution (fbclid, gclid, UTMs)
4. Event is created with source: 'stripe' and attribution data
5. Conversion rules fire postbacks to Meta, Google, TikTok

​

Step 1: Get Webhook URL

1. Log in to DATALYR dashboard
2. Navigate to Sources tab
3. Click Webhooks tab
4. Click Stripe card
5. Copy your webhook URL

https://webhooks.datalyr.com/stripe/YOUR_WORKSPACE_ID

​

Step 2: Configure Stripe Webhook

​

Add Webhook Endpoint

1. Log in to Stripe Dashboard
2. Navigate to Developers → Webhooks
3. Click Add endpoint
4. Paste your DATALYR webhook URL
5. Click Select events

​

Select Events

• checkout.session.completed
• customer.subscription.created
• invoice.payment_succeeded (optional, for recurring payments)

​

Get Signing Secret

1. Click on the webhook endpoint
2. Click Reveal next to Signing secret
3. Copy the secret (starts with whsec_)
4. Return to DATALYR webhook setup modal
5. Paste the signing secret
6. Click Save

​

Step 3: Verify Setup

​

Test with Stripe CLI

# Forward webhooks to DATALYR
stripe listen --forward-to https://webhooks.datalyr.com/stripe/YOUR_WORKSPACE_ID

# Trigger test checkout
stripe trigger checkout.session.completed

​

Test with Real Checkout

1. Create a test product in Stripe
2. Visit your site with ad parameters: yoursite.com?fbclid=test123
3. Call datalyr.identify({ email: '[email protected]' })
4. Complete Stripe checkout with the same email
5. Check DATALYR Event Stream

• A purchase event with source: 'stripe'
• Attribution data (fbclid, visitor_id) from original session
• Event value matching Stripe amount

​

Step 4: Create Conversion Rules

​

Example: Meta Purchase Event

1. Navigate to Integrations → Conversion Rules
2. Click Create Rule
3. Configure rule:

• Event Name: purchase
• Event Source: stripe

• Platform: Meta Ads
• Event Type: Purchase

• Use event value from webhook

​

Event Data Structure

{
  "event_id": "stripe_cs_abc123",
  "workspace_id": "uuid",
  "event_name": "purchase",
  "source": "stripe",

  "visitor_id": "original_visitor_id",
  "user_id": "[email protected]",
  "fbclid": "original_fbclid",
  "gclid": "original_gclid",

  "value": 99.00,
  "currency": "USD",

  "event_data": {
    "session_id": "cs_abc123",
    "customer_id": "cus_abc123",
    "payment_intent": "pi_abc123",
    "mode": "payment",
    "status": "paid"
  }
}

​

Attribution Match Rate

• 95%+ match rate when email is captured before checkout
• 90%+ match rate for cross-device (mobile ad → desktop purchase)
• 85%+ match rate for 30+ day attribution windows

​

Maximize Match Rate

// When user submits email form (before Stripe)
document.getElementById('email-form').addEventListener('submit', function(e) {
  const email = document.getElementById('email').value;

  datalyr.identify({
    email: email
  });
});

// Or on page load if user is logged in
if (currentUser) {
  datalyr.identify({
    email: currentUser.email,
    name: currentUser.name
  });
}

​

Value Calculation

• Checkout sessions: amount_total / 100 (Stripe uses cents)
• Subscriptions: Monthly value calculated from billing interval
  • Annual: amount / 100 / 12
  • Monthly: amount / 100
  • One-time: amount / 100

​

Deduplication

1. Extract event.id from webhook
2. Check if workspace_id:event_id exists in KV
3. If exists, return 200 OK but skip processing
4. If new, process and store in KV

​

Security

1. Extract Stripe-Signature header
2. Verify signature matches webhook secret
3. Reject invalid signatures with 401 Unauthorized

​

Troubleshooting

​

Events have no attribution data

1. Add datalyr.identify({ email }) on email capture forms
2. Ensure identify call happens before Stripe checkout redirect
3. Test by checking Event Stream for identify events with the same visitor_id

​

Webhooks not appearing in Event Stream

1. Check Stripe Dashboard → Webhooks → verify endpoint is active
2. Click webhook endpoint → check for delivery errors
3. Verify signing secret in DATALYR matches Stripe
4. Test with Stripe CLI to see error details

​

Signature verification failed

1. Get signing secret from Stripe webhook endpoint
2. Return to DATALYR webhook setup modal
3. Paste and save the signing secret
4. Trigger new test event

​

Wrong event value

1. Check event_data.amount_total in Event Stream
2. Verify currency is correct (DATALYR uses uppercase)
3. For subscriptions, check billing interval in event_data.interval
4. Contact support if amounts are incorrect

​

What Happens Next

1. Postback Worker checks for matching conversion rules
2. Rules filtered by trigger_event_source: 'stripe'
3. Conversions fire to Meta, Google, TikTok with original attribution
4. Ad platforms receive events with fbclid/gclid for optimization

​

Stripe Revenue Analytics (Separate Feature)

• Real-time conversion tracking
• Fires events to ad platforms
• No OAuth required

• Dashboard metrics (MRR, ARR, churn)
• Requires API key connection
• Periodic data sync

​

Next Steps

• Create conversion rules for Stripe events
• Set up Superwall webhooks
• Set up RevenueCat webhooks
• Monitor webhook events in Event Stream