Webhook Security Implementation Guide

Overview

This document provides a comprehensive guide to implementing secure webhook handling in Shipkit, with specific focus on Lemon Squeezy integration and payment processing webhooks.

🚨 Critical Security Requirements

1. Signature Verification

  • ALWAYS verify webhook signatures using timing-safe comparison
  • Never accept webhooks without proper signature validation
  • Use environment variables for webhook secrets (LEMONSQUEEZY_WEBHOOK_SECRET)

2. Idempotency

  • Store processed webhook event IDs to prevent duplicate processing
  • Use database transactions for atomic operations
  • Handle race conditions with proper locking mechanisms

3. Error Handling

  • Return proper HTTP status codes (200 for success, 4xx for client errors)
  • Never expose internal error details in webhook responses
  • Implement comprehensive logging (excluding sensitive data)

Implementation Files

Core Implementation

  • src/app/(app)/webhooks/lemonsqueezy/route.ts - Main webhook handler
  • docs/integrations/security/LEMONSQUEEZY_WEBHOOK_SECURITY_AUDIT.md - Security audit checklist
  • docs/integrations/lemonsqueezy-webhooks-best-practices.md - Comprehensive guide

Configuration

  • src/env.ts - Environment variable validation
  • Environment variables required:
    • LEMONSQUEEZY_WEBHOOK_SECRET - For signature verification
    • DATABASE_URL - For webhook event storage
    • LEMONSQUEEZY_API_KEY - For API operations

Best Practices Documentation

Rule Files (in .cursor/rules/)

  • webhook-security.mdc - Comprehensive webhook security practices
  • payments.mdc - Payment processing best practices
  • security.mdc - Updated with webhook security sections
  • error-handling.mdc - Updated with webhook error handling
  • database.mdc - Updated with webhook data patterns

Quick Security Checklist

✅ Webhook signature verification implemented with timing-safe comparison ✅ Environment variables properly configured and validated ✅ Idempotency implemented using unique event identifiers ✅ Database transactions used for atomic operations ✅ Comprehensive error handling with proper HTTP status codes ✅ Sensitive data excluded from logs ✅ Rate limiting implemented ✅ Monitoring and alerting configured

Testing

  • Test webhook endpoints in Lemon Squeezy sandbox environment
  • Verify signature validation with invalid signatures
  • Test idempotency with duplicate events
  • Test error handling scenarios

Monitoring

  • Track webhook success/failure rates
  • Monitor processing times
  • Set up alerts for webhook failures
  • Regular security audits

Compliance

  • PCI DSS compliance for payment webhooks
  • GDPR compliance for customer data processing
  • Regular security assessments

Support Documentation