Skip to main content
Internal Documentation Only: If you’re not a Null Tools developer, you can close this documentation or visit the Apps section to learn more about using Null Pass in your applications.

​
Overview

Null Pass integrates with Polar.sh for subscription management. Webhooks from Polar are received and processed to update user service entitlements automatically.

​
Supported Webhooks

DROP Webhooks

/api/webhooks/drop

MAILS Webhooks

/api/webhooks/mails

VAULT Webhooks

/api/webhooks/vault

DB Webhooks

/api/webhooks/db

​
Webhook Endpoints

Each service has its own webhook endpoint:
  • POST /api/webhooks/drop
  • POST /api/webhooks/mails
  • POST /api/webhooks/vault
  • POST /api/webhooks/db

​
Webhook Processing

All webhooks are processed by handlePolarWebhook() in lib/webhook-handlers.ts. The handler:
  1. Sends Discord notification (if configured)
  2. Processes webhook based on event type
  3. Updates user entitlements
  4. Creates audit log entries
  5. Handles errors gracefully

​
Supported Events

​
event
Checkout status update
​
event
New subscription created
  • Updates user entitlement
  • Sets premium status if active
  • Sends payment success notification
  • Creates audit log
​
event
Subscription updated
  • Updates entitlement with new status
  • Adjusts premium flag
  • Creates audit log
​
event
Subscription activated
  • Same as subscription.updated
​
event
Subscription canceled
  • Marks subscription as canceled
  • Access continues until period end
  • Creates audit log
​
event
Subscription revoked
  • Immediately removes premium access
  • Resets to free tier
  • Creates audit log
​
event
Customer created
  • Links Polar customer ID to user
  • Creates entitlement if needed
​
event
Customer updated
  • Updates Polar customer ID
​
event
Customer deleted
  • Removes Polar customer link
  • Resets to free tier

​
Webhook Security

Webhooks are secured using Polar’s webhook secret verification:
​
string
required
Webhook secret for DROP service
​
string
required
Webhook secret for MAILS service
​
string
required
Webhook secret for VAULT service
​
string
required
Webhook secret for DB service

​
Implementation

​
Code Reference

​
User Identification

Webhooks identify users through:
  1. metadata.userId in subscription/customer object (preferred)
  2. Customer email lookup if userId not present

​
Subscription Status Mapping

  • active → isPremium: true, tier set from metadata
  • canceled → Status marked as canceled, access continues
  • revoked → isPremium: false, tier reset to “free”

​
Audit Events

Webhooks create the following audit log entries:
  • SUBSCRIPTION_CREATE
  • SUBSCRIPTION_UPDATE
  • SUBSCRIPTION_CANCEL
  • SUBSCRIPTION_REVOKE

​
Error Handling

  • Errors are logged but don’t fail the webhook
  • Discord notifications failures don’t block processing
  • Database errors are caught and logged
  • Webhook processing continues even if individual steps fail