Skip to main content

​
Overview

BeatPass uses inbound webhooks to receive payment notifications from Stripe. There is currently no outbound webhook system for external integrations.
BeatPass does not send webhooks to external applications. This page documents how BeatPass receives payment notifications from Stripe.

​
Inbound Webhooks (Stripe)

BeatPass receives webhooks from Stripe to process purchase-related payment events.

​
Webhook Endpoint

POST /api/stripe/webhook
This endpoint receives payment-related events from Stripe’s webhook system.
Webhook requests must include a valid Stripe-Signature header. Manual requests without proper signatures are rejected.

​
Stripe Events Handled

The webhook controller processes the following Stripe events:

payment_intent.succeeded

Success Marks purchase as succeeded, generates exclusive license certificate, marks track as sold.
Failed Marks purchase as failed and stores the error message for display.
Refund Marks purchase as refunded (handles both partial and full refunds).

​
How It Works

1

Payment Initiated

User initiates a track purchase via Stripe.js.
2

Stripe Processes

Stripe processes the payment and updates the PaymentIntent status.
3

Webhook Sent

Stripe sends a webhook to BeatPass at /api/stripe/webhook.
4

BeatPass Processes

BeatPass verifies the signature and processes the event:
  • Updates purchase/payout records
  • Generates license certificates for successful purchases
  • Marks tracks as sold for exclusive purchases
  • Sends notifications to producers

​
Webhook Security

​
Stripe Signature Verification

All incoming Stripe webhooks are verified using Stripe’s standard webhook signature verification. This ensures that webhook payloads are authentic and have not been tampered with.
  • Webhooks are validated against a signing secret configured in Stripe
  • Invalid signatures result in immediate rejection (400 response)
  • All webhook processing is logged for audit purposes
Webhooks without valid Stripe signatures are rejected. Only Stripe’s servers can send valid webhook events.

​
For Developers

​
Testing Webhooks Locally

Use the Stripe CLI to forward webhooks during development: 
# Install Stripe CLI
brew install stripe/stripe-cli/stripe

# Login
stripe login

# Forward webhooks to a local development server
stripe listen --forward-to localhost:8000/api/stripe/webhook

# Forward webhooks to a remote dev server (example)
stripe listen --forward-to https://dev.example.com/api/stripe/webhook

​
Webhook Events in Stripe Dashboard

Monitor webhook delivery in the Stripe Dashboard:
  1. Go to Developers > Webhooks
  2. Select your endpoint
  3. View recent events and delivery status
  4. Retry failed webhooks if needed

​
No Outbound Webhooks

BeatPass does not currently offer outbound webhooks for external integrations.
For real-time updates in your application:
  • Track changes: Poll the API or use the notifications SSE stream (authenticated)
  • Purchase status: Use the purchase status endpoint after initiating
  • User events: Handled client-side via the BeatPass frontend

​
Future Considerations

Outbound webhooks for third-party integrations may be considered for future releases. If you have a specific use case, contact support to discuss.

Exclusive Licenses

How exclusive purchases and licensing work.

Stripe Connect

Producer payout setup guide.
Last modified on December 5, 2025