polar-integration-validator
Autonomous validation of Polar.sh billing integration. Checks webhook endpoints, signature verification, subscription middleware, and environment configuration.
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.
| name | polar-integration-validator |
|---|---|
| description | Autonomous 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.tomlis 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.tsor similar) - ✅ Signature verification implemented (
polar.webhooks.verify) - ✅ All critical events handled:
checkout.completed,subscription.created,subscription.updated,subscription.canceled
Environment Variables:
- ✅
POLAR_ACCESS_TOKENconfigured (check.dev.varsor secrets) - ✅
POLAR_WEBHOOK_SECRETin wrangler.toml
Database:
- ✅ Users table has
polar_customer_idcolumn - ✅ Subscriptions table exists
- ✅ Foreign key relationship configured
P2 - Important (Warn)
Event Handling:
- ⚠️
subscription.past_duehandler 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_endnot 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
/validateand/es-deploycommands