Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.nullpass.xyz/llms.txt

Use this file to discover all available pages before exploring further.

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

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

​
Webhook Security

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

​
Implementation

​
Code Reference

export const POST = Webhooks({
  webhookSecret: process.env.DROP_POLAR_SECRET!,
  
  onPayload: async (payload) => {
    await handlePolarWebhook(payload, 'DROP')
  },
})

​
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