116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
# 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**
|
|
```bash
|
|
stripe login
|
|
```
|
|
|
|
2. **Forward webhook events to your local server**
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
STRIPE_WH_SEC=whsec_1234567890abcdef...
|
|
```
|
|
|
|
5. **Enable debug logging**
|
|
Set the DEBUG environment variable to see webhook processing logs:
|
|
```bash
|
|
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**
|
|
```bash
|
|
# 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
|
|
|
|
|