Skip to main content

​
Overview

Pwnbook uses Stripe for subscription billing. Billing is entirely optional — if you don’t configure Stripe, all features are available without restriction. When billing is enabled, organizations are placed on plans (Starter, Business, Enterprise) that control their access to specific features and seat limits.
For self-hosted deployments used internally by a single organization, you likely don’t need to configure billing. Skip this section unless you are running Pwnbook as a multi-tenant SaaS.

​
Enabling billing

To enable billing, you need a Stripe account and a secret key:
  1. Create or log in to your Stripe account.
  2. Obtain your Secret Key from Developers → API Keys. Use the live key for production, test key for testing.
  3. Add the key to your Pwnbook environment:
STRIPE_SECRET_KEY=sk_live_...
  1. Restart the backend service:
docker compose restart backend
Once the STRIPE_SECRET_KEY is set, billing features are activated and visible in the admin panel.

​
Configuring subscription plans

Pwnbook maps Stripe products and prices to internal plan tiers. To configure this:
  1. In Stripe, create products for each plan (Starter, Business, Enterprise).
  2. Add a price to each product (monthly and/or annual).
  3. In the Pwnbook admin panel, go to Billing → Plan Configuration.
  4. Map each Stripe price ID to the corresponding Pwnbook plan tier.
  5. Set the feature limits for each plan (seats, engagements, etc.).
  6. Save.

​
Plan tiers

PlanDescription
StarterFor small teams. Basic feature set, limited seats.
BusinessGrowing teams. Includes custom roles, SSO, API access, and priority support.
EnterpriseLarge organizations. Custom pricing, dedicated support, SLA, and self-hosting options.

​
Setting up Stripe webhooks

Stripe uses webhooks to notify Pwnbook of billing events (payment succeeded, subscription cancelled, etc.). Without webhooks configured, subscription status changes won’t be reflected in Pwnbook.
1

Get your webhook endpoint URL

Your Pwnbook webhook endpoint is:
https://your-pwnbook-domain.com/api/billing/webhook
Replace your-pwnbook-domain.com with your actual domain.
2

Create the webhook in Stripe

  1. In the Stripe dashboard, go to Developers → Webhooks.
  2. Click Add endpoint.
  3. Enter your webhook endpoint URL.
  4. Select the events to listen to (see Webhook events below).
  5. Click Add endpoint.
3

Add the webhook secret to Pwnbook

After creating the webhook, Stripe provides a Signing Secret.Add it to your environment:
STRIPE_WEBHOOK_SECRET=whsec_...
Restart the backend:
docker compose restart backend

​
Webhook events

Configure Stripe to send the following events to your webhook endpoint:
EventDescription
customer.subscription.createdA new subscription was activated
customer.subscription.updatedSubscription plan or status changed
customer.subscription.deletedSubscription was cancelled
invoice.payment_succeededA payment was successfully processed
invoice.payment_failedA payment attempt failed
customer.createdA new Stripe customer was created

​
Managing organization subscriptions

From the admin panel’s Billing section, you can view and manage subscriptions for individual organizations:
  1. Go to Server Admin → Billing → Organizations.
  2. Find the organization and click on it.
  3. View current plan, billing cycle, next payment date, and payment method.

​
Upgrading or downgrading a plan

To change an organization’s plan:
  1. Open the organization in the Billing admin.
  2. Click Change Plan.
  3. Select the new plan.
  4. Confirm the change.
Plan changes take effect immediately for upgrades (features become available right away) and at the end of the current billing period for downgrades.

​
Cancelling a subscription

To cancel an organization’s subscription:
  1. Open the organization in the Billing admin.
  2. Click Cancel Subscription.
  3. Choose immediate cancellation or cancel at period end.
  4. Confirm.
After cancellation, the organization is downgraded to the default free tier (if configured) or access to paid features is restricted.

​
Testing billing

Before going live, test your billing configuration using Stripe test mode:
  1. Use a Stripe test secret key (sk_test_...) in your environment.
  2. Use Stripe test cards for payments.
  3. Trigger webhook events using the Stripe CLI: stripe trigger customer.subscription.created.
Switch to live mode keys only when you’re ready to accept real payments.