Skip to main content

Stripe Data Plan Webhook Setup

This project uses a dedicated Stripe webhook endpoint for cellular data plan purchases:

  • https://aovis.app/api/webhooks/data-plan

Keep this endpoint separate from the existing hardware order webhook at /api/stripe/webhook.

Stripe Dashboard steps​

  1. Open Stripe Dashboard.
  2. Go to Developers -> Webhooks.
  3. Click Add endpoint.
  4. Set the endpoint URL to:
    • https://aovis.app/api/webhooks/data-plan
  5. Do not edit the existing hardware order webhook endpoint.
    • Recommendation: add a second webhook endpoint just for data plans so the hardware order flow stays isolated.

Events to subscribe to​

Subscribe the new endpoint to these Stripe events:

  • checkout.session.completed
  • payment_intent.succeeded
  • payment_intent.payment_failed
  • charge.refunded

Important note:

  • Stripe does not support filtering webhook events by metadata.type at the Dashboard level.
  • Filtering must happen in application code.
  • The current implementation in app/api/webhooks/data-plan/route.ts already checks session.metadata.type === 'data_plan' before creating a DataPlanPurchase.
  • Unrelated events are acknowledged with 200 so Stripe does not retry them.

Signing secret​

After creating the endpoint:

  1. Open the new endpoint details page.
  2. Click Reveal under Signing secret.
  3. Copy the whsec_... value.
  4. Store it on the VM in:
    • STRIPE_DATA_PLAN_WEBHOOK_SECRET=whsec_...

This variable must be appended to the VM's .env.production manually. It should not be committed to git and should not be bulk-overwritten.

Verification checklist​

After the endpoint is created and the secret is added to the VM:

  1. Send a test event from Stripe Dashboard to the new endpoint.
  2. Confirm Stripe shows the delivery as 200.
  3. Check server logs for the received event:
    • pm2 logs aovis-store-staging --lines 200
  4. Run a real or test data-plan purchase and confirm a DataPlanPurchase row is created.