Troubleshoot Stripe Affiliate Webhooks

Stripe webhooks deliver payment events that AffiliateBase uses for sale and commission attribution. Use this guide when Stripe deliveries fail, arrive in the wrong mode, or succeed without creating an attributed conversion.

How Webhooks Work

Customer pays → Stripe processes → Webhook fires →
AffiliateBase receives → Conversion created

Key affiliate-attribution events:

• payment_intent.succeeded
• invoice.paid / invoice.payment_succeeded
• checkout.session.completed / checkout.session.async_payment_succeeded
• refund.updated / charge.refunded
• charge.dispute.created, charge.dispute.updated, and charge.dispute.closed

Checking Webhook Status

In Stripe Dashboard

1. Go to Stripe Dashboard
2. Navigate to Developers → Webhooks
3. Find the AffiliateBase endpoint
4. Check status and recent deliveries

Webhook Health Indicators

Status	Meaning
Enabled	Webhook is active
Disabled	Webhook turned off
Failing	Recent delivery failures

Recent Attempts

Click on the endpoint to see:

• Recent delivery attempts
• Success/failure status
• Response codes
• Payload details

Common Issues & Solutions

Issue: Webhook Endpoint Not Found

Symptom: No AffiliateBase webhook in Stripe.

Cause: Stripe connection incomplete or disconnected.

Solution:

1. Go to AffiliateBase Settings → General
2. Check Stripe connection status
3. Click Reconnect Stripe if needed
4. Complete the authorization flow
5. Webhook should be auto-created

Issue: Webhook Deliveries Failing (4xx/5xx)

Symptom: Webhook attempts show error codes.

Error codes:

Code	Meaning	Solution
400	Bad request	Contact support - may be payload issue
401	Unauthorized	Reconnect Stripe to refresh auth
404	Not found	Endpoint URL changed - reconnect Stripe
500	Server error	Temporary issue - will retry automatically
502/503	Service unavailable	AffiliateBase may be down - check status

General solution:

1. Check AffiliateBase service status
2. Try reconnecting Stripe
3. Resend failed webhooks
4. Contact support if persists

Issue: Webhooks Not Firing

Symptom: No webhook attempts in Stripe for purchases.

Causes:

• Wrong events configured
• Test mode vs live mode mismatch
• Webhook disabled

Solutions:

1. Check event types:

   • Click webhook endpoint
   • Verify the affiliate-attribution events above are included
   • Reconnect Stripe in AffiliateBase if the managed endpoint is missing required events

2. Check mode:

   • Ensure webhook matches your mode (test/live)
   • Test mode purchases → test webhook
   • Live mode purchases → live webhook

3. Verify webhook is enabled:

   • Endpoint should show “Enabled”
   • Re-enable if disabled

Issue: Webhook Signature Verification Failed

Symptom: 401 errors mentioning signature.

Cause: Signing secret mismatch.

Solution:

1. Reconnect Stripe in AffiliateBase
2. This refreshes the signing secret
3. Webhook signature should verify again

Issue: Events Received but Conversions Not Created

Symptom: Webhooks show 200 success but no conversions appear.

Causes:

• client_reference_id missing from checkout
• client_reference_id contains a public ?via link token instead of the generated referral ID
• Referral not found
• Attribution window expired

Solutions:

1. Check the webhook payload:

   • Click on a delivered event
   • Look at the payload
   • Find client_reference_id field

2. If client_reference_id is empty:

   • Review your checkout code
   • Ensure referral passed to Stripe

3. If client_reference_id starts with ref_ or setup_:

   • Your checkout is sending the public affiliate link token from ?via
   • Stripe needs the generated AffiliateBase referral ID created by the tracking script
   • For Payment Links, remove custom code that copies ?via into Stripe and let the AffiliateBase script update the link
   • For backend-created Checkout Sessions, submit the generated referral_id from the browser to your server, then set Stripe client_reference_id

4. If client_reference_id exists and does not start with ref_ or setup_:

   • Check if that referral exists in AffiliateBase
   • Verify attribution window hasn’t expired

Webhook Endpoint Details

Expected Endpoint Format

https://app.affiliatebase.io/api/stripe/webhook

Required Events

AffiliateBase needs these events:

• payment_intent.succeeded
• invoice.paid
• invoice.payment_succeeded
• checkout.session.completed
• checkout.session.async_payment_succeeded
• refund.updated
• charge.refunded
• charge.dispute.created
• charge.dispute.updated
• charge.dispute.closed

AffiliateBase also uses separate billing and Stripe app lifecycle webhook endpoints for plan billing and Stripe app authorization events. Do not mix those with the merchant affiliate-events endpoint.

Testing Webhooks

Send Test Event

In Stripe Dashboard:

1. Go to webhook endpoint
2. Click Send test webhook
3. Select event type (e.g., invoice.paid)
4. Click Send test event
5. Check response

Test with Real Payment

1. Use Stripe test mode
2. Make a test purchase
3. Verify webhook fires
4. Check AffiliateBase for conversion

Webhook Logs

View detailed logs:

1. Click on a webhook attempt
2. See request/response details
3. View full payload
4. Check timing information

Resending Failed Webhooks

Individual Event

1. Find the failed event
2. Click Resend
3. Monitor for success

Bulk Resend

For multiple failures:

1. Use Stripe CLI: stripe events resend
2. Or contact Stripe support for bulk replay

Webhook Security

Signature Verification

All webhooks are verified:

• Stripe signs each event
• AffiliateBase verifies signature
• Prevents forged events

Endpoint Security

• HTTPS only
• No authentication required (signature verifies)
• Rate limiting in place

Monitoring & Alerts

Stripe Alerts

Set up Stripe webhook alerts:

1. Go to Developers → Webhooks
2. Enable email notifications
3. Get alerted on failures

Recommended Monitoring

1. Check daily: Review webhook delivery status
2. Alert on failures: Set up notifications
3. Test regularly: Run test conversions weekly

Advanced Troubleshooting

Using Stripe CLI

Install Stripe CLI for local testing:

# Install
brew install stripe/stripe-cli/stripe

# Login
stripe login

# Forward webhooks to local
stripe listen --forward-to localhost:3000/api/stripe/webhook

# Trigger test events
stripe trigger checkout.session.completed

Viewing Raw Events

In Stripe Dashboard:

1. Go to Developers → Events
2. Find the event
3. View full payload
4. Check data.object for details

Checking Event Processing

Look for in the event:

{
  "data": {
    "object": {
      "client_reference_id": "your-referral-id",
      "customer": "cus_xxxxx",
      "amount_total": 9900
    }
  }
}

The value should be the generated AffiliateBase referral ID for that visitor. If it begins with ref_ or setup_, Stripe received the public affiliate link token instead, and AffiliateBase will not create an attributed conversion from that webhook.

When to Contact Support

Contact AffiliateBase support if:

• Webhooks consistently failing with 500 errors
• Conversions not creating despite successful webhooks
• Need webhook endpoint changed
• Signature verification issues persist

Contact Stripe support if:

• Can’t access webhook settings
• Events not appearing at all
• Need historical event replay
• API/dashboard issues

Prevention

Best Practices

1. Don’t modify webhook URL manually - use reconnect flow
2. Monitor regularly - check webhook health weekly
3. Keep Stripe connected - reconnect if token expires
4. Test after changes - verify webhooks work

Maintenance

1. Reconnect Stripe periodically if issues arise
2. Review webhook configuration after Stripe updates
3. Reconnect Stripe from AffiliateBase if endpoint configuration drifts

Next steps

• Troubleshooting Common Issues
• Connect Stripe
• Stripe Checkout and Payment Links