agmission/Development/server/README.md

AgMission Server

Environment keys

Syntax	Description
AGM_PORT	BackEnd endpoint port
PRODUCTION	Whether runnung in production mode
DEBUG	debug pattern. E.g:
AGM_PORT	BackEnd endpoint port DEBUG=agm:*
STRIPE_SECRET_KEY	Stripe secret key
STRIPE_PUBLISHABLE_KEY	Stripe publishable key
STRIPE_API_VERSION	Stripe API Version
STRIPE_WH_SEC	Stripe Webhooks Endpoint secret
[Package]_[Number]	Stripe package in uppercased 3-first character and number. E.g: ESS_1 for essential package 1

Debug Stripe Webhook

Prerequisites

1. Install Stripe CLI: https://stripe.com/docs/stripe-cli
2. Make sure your server is running locally
3. Have your Stripe account credentials ready

Setup Steps

1. Login to Stripe CLI

   stripe login
   

2. Forward webhook events to your local server

   # Forward to local development server (default port 3000)
   stripe listen --forward-to https://localhost:4100/stripe_webhooks --skip-verify
   
   # Or specify custom port if your AGM_PORT is different
   stripe listen --forward-to localhost:YOUR_AGM_PORT/webhook/stripe
   

3. Get the webhook signing secret When you run the stripe listen command, it will output a webhook signing secret like:

   > Ready! Your webhook signing secret is whsec_1234567890abcdef...
   

4. Update your environment variables Add or update the webhook secret in your .env file:

   STRIPE_WH_SEC=whsec_1234567890abcdef...
   

5. Enable debug logging Set the DEBUG environment variable to see webhook processing logs:

   DEBUG=agm:* npm start
   # Or specifically for webhook debugging:
   DEBUG=agm:webhook,agm:stripe npm start
   

Testing Webhook Events

1. Trigger test events from Stripe CLI

   # Test subscription created event
   stripe trigger invoice.payment_succeeded
   
   # Test subscription updated event
   stripe trigger customer.subscription.updated
   
   # Test payment failed event
   stripe trigger invoice.payment_failed
   
   # Test subscription cancelled event
   stripe trigger customer.subscription.deleted
   

2. Create test events from Stripe Dashboard

   • Go to your Stripe Dashboard
   • Navigate to Developers > Webhooks
   • Click "Send test webhook"
   • Select the event type you want to test

Debug Output

When debugging is enabled, you should see output like:

agm:webhook Received Stripe webhook: invoice.payment_succeeded
agm:stripe Processing subscription payment for customer: cus_...
agm:db -> MongoDB connected - Main Application ready

Common Issues

1. Webhook signature verification failed

   • Make sure STRIPE_WH_SEC matches the secret from stripe listen
   • Ensure the webhook endpoint path is correct (/webhook/stripe)

2. Connection refused

   • Verify your server is running on the correct port
   • Check that the --forward-to URL matches your server address

3. No webhook events received

   • Confirm stripe listen is still running
   • Check that events are being sent to the correct endpoint
   • Verify your webhook endpoint is accessible

Production Webhook Setup

For production, configure webhooks directly in your Stripe Dashboard:

1. Go to Developers > Webhooks
2. Click "Add endpoint"
3. Set endpoint URL: https://yourdomain.com/webhook/stripe
4. Select events to listen for
5. Copy the signing secret to your production STRIPE_WH_SEC environment variable