polar-integration-validator

Autonomous validation of Polar.sh billing integration. Checks webhook endpoints, signature verification, subscription middleware, and environment configuration.

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 19, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill provides autonomous validation for Polar.sh billing integrations, ensuring that webhook endpoints, signature verification, subscription middleware, and environment configurations are correctly implemented to prevent revenue loss and security vulnerabilities during the development lifecycle.

Use Cases

  • Automated Webhook Security Audit: Verifies that signature verification (polar.webhooks.verify) is correctly implemented to prevent spoofing and unauthorized billing events.
  • Pre-deployment Integration Check: Scans for missing environment variables like POLAR_ACCESS_TOKEN and required database schema columns before code is pushed to production.
  • Subscription Middleware Validation: Ensures that protected routes are correctly gated by checking for active subscription status and valid expiration dates.
  • Event Handler Coverage: Confirms that critical billing events such as subscription creation, updates, and cancellations are properly handled within the codebase to maintain data consistency.
namepolar-integration-validator
descriptionAutonomous validation of Polar.sh billing integration. Checks webhook endpoints, signature verification, subscription middleware, and environment configuration.
triggers["webhook file changes", "subscription code changes", "wrangler.toml updates", "billing-related modifications"]

Polar Integration Validator SKILL

Activation Patterns

This SKILL automatically activates when:

  • Files matching **/webhooks/polar.* are created/modified
  • Files containing "subscription" or "polar" in path are modified
  • wrangler.toml is updated
  • Environment variable files (.dev.vars, .env) are modified
  • Before deployment operations

Validation Rules

P1 - Critical (Block Operations)

Webhook Endpoint:

  • ✅ Webhook handler exists (server/api/webhooks/polar.ts or similar)
  • ✅ Signature verification implemented (polar.webhooks.verify)
  • ✅ All critical events handled: checkout.completed, subscription.created, subscription.updated, subscription.canceled

Environment Variables:

  • ✅ POLAR_ACCESS_TOKEN configured (check .dev.vars or secrets)
  • ✅ POLAR_WEBHOOK_SECRET in wrangler.toml

Database:

  • ✅ Users table has polar_customer_id column
  • ✅ Subscriptions table exists
  • ✅ Foreign key relationship configured

P2 - Important (Warn)

Event Handling:

  • ⚠️ subscription.past_due handler exists
  • ⚠️ Database updates in all event handlers
  • ⚠️ Error logging implemented

Subscription Middleware:

  • ⚠️ Subscription check function exists
  • ⚠️ Used on protected routes
  • ⚠️ Checks subscription_status === 'active'
  • ⚠️ Checks current_period_end not expired

P3 - Suggestions (Inform)

  • ℹ️ Webhook event logging to database
  • ℹ️ Customer creation helper function
  • ℹ️ Subscription status caching
  • ℹ️ Rate limiting on webhook endpoint

Validation Output

🔍 Polar.sh Integration Validation

✅ P1 Checks (Critical):
   ✅ Webhook endpoint exists
   ✅ Signature verification implemented
   ✅ Environment variables configured
   ✅ Database schema complete

⚠️ P2 Checks (Important):
   ⚠️ Missing subscription.past_due handler
   ✅ Subscription middleware exists
   ✅ Protected routes check subscription

ℹ️ P3 Suggestions:
   ℹ️ Consider adding webhook event logging
   ℹ️ Add rate limiting to webhook endpoint

📋 Summary: 1 warning found
💡 Run /es-billing-setup to fix issues

Escalation

Complex scenarios escalate to polar-billing-specialist agent:

  • Custom webhook processing logic
  • Multi-tenant subscription architecture
  • Usage-based billing implementation
  • Migration from other billing providers

Notes

  • Runs automatically on relevant file changes
  • Can block deployments with P1 issues
  • Queries Polar MCP for product validation
  • Integrates with /validate and /es-deploy commands