Stripe Webhook Issues

Stripe webhooks notify AffiliateBase about payment events. If webhooks aren’t working, conversions won’t track. This guide helps diagnose and fix webhook issues.

How Webhooks Work

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

Key events:

• invoice.paid - Primary event for conversion tracking
• checkout.session.completed - Session completion
• charge.refunded - Refund processing

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 invoice.paid is included
   • Add missing events if needed

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
• 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 exists:

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

Webhook Endpoint Details

Expected Endpoint Format

https://api.affiliatebase.com/webhooks/stripe/{organization_id}

Required Events

AffiliateBase needs these events:

• invoice.paid (required for conversions)
• invoice.payment_failed (optional)
• charge.refunded (for refund handling)
• checkout.session.completed (for session data)

Webhook Version

Uses latest Stripe API version for your account.

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/webhook

# Trigger test events
stripe trigger invoice.paid

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
    }
  }
}

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. Update to latest Stripe API version when prompted
3. Review webhook configuration after Stripe updates

Related Guides

• Conversions Not Tracking
• Connecting Your Stripe Account
• Stripe Checkout Integration