Volley + Stripe Webhook Example

Complete example of testing Stripe webhooks locally using Volley - No ngrok, no tunneling, no exposing your server.

This repository demonstrates how to test Stripe webhooks locally using Volley, a webhook-as-a-service platform. Unlike ngrok, Volley provides permanent webhook URLs and doesn't require tunneling.

🎯 What You'll Learn

• How to set up Stripe webhooks with Volley
• How to test webhooks locally without exposing your server
• How to handle Stripe webhook events in Node.js/Express
• Best practices for webhook security and verification

🚀 Quick Start

Prerequisites

• Node.js 18+ installed
• A Volley account (free tier: 10K events/month)
• A Stripe account (test mode is fine)
• Volley CLI installed

Installation

1. Clone this repository:

   git clone https://github.com/volleyhq/volley-stripe-example.git
   cd volley-stripe-example

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your Stripe secret key

4. Create a Volley source:

   • Go to Volley Dashboard
   • Create a new organization and project
   • Create a new source (e.g., "stripe-webhooks")
   • Copy your ingestion ID (e.g., abc123xyz)

5. Configure Stripe webhook:

   • Go to Stripe Dashboard
   • Click "Add endpoint"
   • Enter your Volley webhook URL: https://api.volleyhooks.com/hook/YOUR_INGESTION_ID
   • Select events to listen to (e.g., payment_intent.succeeded, customer.created)
   • Click "Add endpoint"

6. Start your local server:

   npm start

7. Forward webhooks to localhost:

   volley listen --source YOUR_INGESTION_ID --forward-to http://localhost:3000/webhooks/stripe

8. Test it:

   • Trigger a test event in Stripe Dashboard
   • Watch it appear in your local server logs!

📁 Project Structure

volley-stripe-example/
├── src/
│   ├── server.js          # Express server setup
│   ├── webhookHandler.js  # Stripe webhook handler
│   └── handlers/          # Event-specific handlers
│       ├── paymentIntent.js
│       ├── customer.js
│       └── invoice.js
├── .env.example           # Environment variables template
├── package.json
└── README.md

💻 Code Example

Basic Webhook Handler

// src/webhookHandler.js
const express = require('express');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

const router = express.Router();

// Stripe webhook endpoint
router.post('/webhooks/stripe', express.raw({ type: 'application/json' }), async (req, res) => {
  const sig = req.headers['stripe-signature'];
  let event;

  try {
    // Verify webhook signature
    event = stripe.webhooks.constructEvent(
      req.body,
      sig,
      process.env.STRIPE_WEBHOOK_SECRET
    );
  } catch (err) {
    console.error('Webhook signature verification failed:', err.message);
    return res.status(400).send(`Webhook Error: ${err.message}`);
  }

  // Handle the event
  switch (event.type) {
    case 'payment_intent.succeeded':
      await handlePaymentIntentSucceeded(event.data.object);
      break;
    case 'customer.created':
      await handleCustomerCreated(event.data.object);
      break;
    case 'invoice.payment_succeeded':
      await handleInvoicePaymentSucceeded(event.data.object);
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }

  // Return a response to acknowledge receipt
  res.json({ received: true });
});

module.exports = router;

Event Handlers

// src/handlers/paymentIntent.js
async function handlePaymentIntentSucceeded(paymentIntent) {
  console.log('Payment succeeded:', paymentIntent.id);
  // Your business logic here
  // e.g., update database, send confirmation email, etc.
}

// src/handlers/customer.js
async function handleCustomerCreated(customer) {
  console.log('Customer created:', customer.id);
  // Your business logic here
}

🔐 Security Best Practices

1. Verify Webhook Signatures

Always verify Stripe webhook signatures to ensure requests are from Stripe:

const event = stripe.webhooks.constructEvent(
  req.body,
  sig,
  process.env.STRIPE_WEBHOOK_SECRET
);

2. Use Environment Variables

Never commit secrets to version control:

# .env
STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

3. Idempotency

Handle duplicate webhooks gracefully:

// Use Stripe event IDs for idempotency
const eventId = event.id;
if (await isEventProcessed(eventId)) {
  return; // Already processed
}
await markEventAsProcessed(eventId);

🧪 Testing

Manual Testing

1. Use Stripe CLI to send test webhooks:

   stripe trigger payment_intent.succeeded

2. Or use Stripe Dashboard:

   • Go to Webhooks → Your endpoint → Send test webhook

Automated Testing

// test/webhook.test.js
const request = require('supertest');
const app = require('../src/server');

describe('Stripe Webhooks', () => {
  it('should handle payment_intent.succeeded', async () => {
    const event = {
      id: 'evt_test',
      type: 'payment_intent.succeeded',
      data: { object: { id: 'pi_test' } }
    };
    
    const response = await request(app)
      .post('/webhooks/stripe')
      .send(JSON.stringify(event))
      .set('stripe-signature', 'test-signature');
    
    expect(response.status).toBe(200);
  });
});

🆚 Why Volley Instead of ngrok?

Feature	Volley	ngrok
Webhook URLs	✅ Permanent, never change	❌ Change on restart
Tunneling	❌ Not required	✅ Required
Local Server Privacy	✅ Completely private	⚠️ Exposed through tunnel
Built-in Retry	✅ Automatic	❌ No
Monitoring	✅ Full dashboard	❌ Limited
Production Ready	✅ Same URL for dev/prod	❌ Dev tool only

Learn more: Volley vs ngrok

📚 Additional Resources

• Volley Documentation
• Stripe Webhooks Guide
• Volley CLI Documentation
• Testing Stripe Webhooks Locally

🤝 Contributing

Found a bug or have a suggestion? Please open an issue or submit a pull request!

📄 License

MIT License - See LICENSE file for details

---

Built with ❤️ using Volley and Stripe