Webhook Handling

This guide shows you how to handle SolvaPay webhooks to keep your application in sync with subscription and payment events.

Table of Contents

• Overview
• Webhook Setup
• Webhook Verification
• Event Handling
• Complete Examples

Overview

SolvaPay sends webhooks to notify your application about important events:

• Subscription Created - New subscription activated
• Subscription Updated - Subscription plan or status changed
• Subscription Cancelled - Subscription cancelled
• Payment Succeeded - Payment processed successfully
• Payment Failed - Payment processing failed

Webhook Flow

SolvaPay Backend
    ↓
Webhook Event
    ↓
Your Webhook Endpoint
    ↓
Verify Signature
    ↓
Process Event
    ↓
Update Your Database

Webhook Setup

1. Configure Webhook Endpoint

Set your webhook endpoint in the SolvaPay dashboard:

https://your-app.com/api/webhooks/solvapay

2. Create Webhook Endpoint

Create an endpoint to receive webhooks:

// app/api/webhooks/solvapay/route.ts (Next.js)
import { NextRequest, NextResponse } from 'next/server';
import { verifyWebhook } from '@solvapay/server';

export async function POST(request: NextRequest) {
  try {
    // Verify webhook signature
    const payload = await request.text();
    const signature = request.headers.get('x-solvapay-signature');
    
    if (!signature) {
      return NextResponse.json(
        { error: 'Missing signature' },
        { status: 401 }
      );
    }
    
    const verified = verifyWebhook(payload, signature, {
      secret: process.env.SOLVAPAY_WEBHOOK_SECRET!,
    });
    
    if (!verified) {
      return NextResponse.json(
        { error: 'Invalid signature' },
        { status: 401 }
      );
    }
    
    // Parse event
    const event = JSON.parse(payload);
    
    // Handle event
    await handleWebhookEvent(event);
    
    return NextResponse.json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    return NextResponse.json(
      { error: 'Webhook processing failed' },
      { status: 500 }
    );
  }
}

Express.js Webhook Endpoint

// routes/webhooks.ts
import express from 'express';
import { verifyWebhook } from '@solvapay/server';

const router = express.Router();

router.post('/solvapay', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    const signature = req.headers['x-solvapay-signature'] as string;
    
    if (!signature) {
      return res.status(401).json({ error: 'Missing signature' });
    }
    
    const payload = req.body.toString();
    const verified = verifyWebhook(payload, signature, {
      secret: process.env.SOLVAPAY_WEBHOOK_SECRET!,
    });
    
    if (!verified) {
      return res.status(401).json({ error: 'Invalid signature' });
    }
    
    const event = JSON.parse(payload);
    await handleWebhookEvent(event);
    
    res.json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Webhook processing failed' });
  }
});

export default router;

Webhook Verification

Verify Webhook Signature

Always verify webhook signatures to ensure requests are from SolvaPay:

import { verifyWebhook } from '@solvapay/server';

const verified = verifyWebhook(payload, signature, {
  secret: process.env.SOLVAPAY_WEBHOOK_SECRET!,
});

if (!verified) {
  // Reject webhook
  return res.status(401).json({ error: 'Invalid signature' });
}

Environment Variables

Set your webhook secret:

SOLVAPAY_WEBHOOK_SECRET=whsec_...

Get your webhook secret from the SolvaPay dashboard.

Event Handling

Event Types

Handle different event types:

interface WebhookEvent {
  type: string;
  data: {
    customerRef: string;
    subscriptionId?: string;
    planRef?: string;
    status?: string;
    // ... other event data
  };
  timestamp: string;
}

Handle Subscription Events

async function handleWebhookEvent(event: WebhookEvent) {
  switch (event.type) {
    case 'subscription.created':
      await handleSubscriptionCreated(event.data);
      break;
    
    case 'subscription.updated':
      await handleSubscriptionUpdated(event.data);
      break;
    
    case 'subscription.cancelled':
      await handleSubscriptionCancelled(event.data);
      break;
    
    case 'payment.succeeded':
      await handlePaymentSucceeded(event.data);
      break;
    
    case 'payment.failed':
      await handlePaymentFailed(event.data);
      break;
    
    default:
      console.log('Unknown event type:', event.type);
  }
}

Subscription Created

async function handleSubscriptionCreated(data: any) {
  const { customerRef, subscriptionId, planRef } = data;
  
  // Update your database
  await db.subscriptions.create({
    customerRef,
    subscriptionId,
    planRef,
    status: 'active',
  });
  
  // Clear subscription cache
  await clearSubscriptionCache(customerRef);
  
  // Send welcome email, etc.
  await sendWelcomeEmail(customerRef);
}

Subscription Updated

async function handleSubscriptionUpdated(data: any) {
  const { customerRef, subscriptionId, planRef, status } = data;
  
  // Update subscription in database
  await db.subscriptions.update({
    where: { subscriptionId },
    data: { planRef, status },
  });
  
  // Clear cache
  await clearSubscriptionCache(customerRef);
}

Subscription Cancelled

async function handleSubscriptionCancelled(data: any) {
  const { customerRef, subscriptionId } = data;
  
  // Update subscription status
  await db.subscriptions.update({
    where: { subscriptionId },
    data: { status: 'cancelled', cancelledAt: new Date() },
  });
  
  // Clear cache
  await clearSubscriptionCache(customerRef);
  
  // Send cancellation email
  await sendCancellationEmail(customerRef);
}

Payment Succeeded

async function handlePaymentSucceeded(data: any) {
  const { customerRef, paymentIntentId, amount } = data;
  
  // Record payment
  await db.payments.create({
    customerRef,
    paymentIntentId,
    amount,
    status: 'succeeded',
  });
  
  // Clear cache
  await clearSubscriptionCache(customerRef);
}

Payment Failed

async function handlePaymentFailed(data: any) {
  const { customerRef, paymentIntentId, error } = data;
  
  // Record failed payment
  await db.payments.create({
    customerRef,
    paymentIntentId,
    status: 'failed',
    error: error.message,
  });
  
  // Notify user
  await sendPaymentFailedEmail(customerRef, error);
}

Complete Examples

Next.js Complete Example

// app/api/webhooks/solvapay/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { verifyWebhook } from '@solvapay/server';
import { clearSubscriptionCache } from '@solvapay/next';

export async function POST(request: NextRequest) {
  try {
    // Get raw body for signature verification
    const payload = await request.text();
    const signature = request.headers.get('x-solvapay-signature');
    
    if (!signature) {
      return NextResponse.json(
        { error: 'Missing signature' },
        { status: 401 }
      );
    }
    
    // Verify webhook signature
    const verified = verifyWebhook(payload, signature, {
      secret: process.env.SOLVAPAY_WEBHOOK_SECRET!,
    });
    
    if (!verified) {
      return NextResponse.json(
        { error: 'Invalid signature' },
        { status: 401 }
      );
    }
    
    // Parse event
    const event = JSON.parse(payload);
    
    // Handle event
    await handleWebhookEvent(event);
    
    return NextResponse.json({ received: true });
  } catch (error) {
    console.error('Webhook error:', error);
    return NextResponse.json(
      { error: 'Webhook processing failed' },
      { status: 500 }
    );
  }
}

async function handleWebhookEvent(event: any) {
  const { type, data } = event;
  
  switch (type) {
    case 'subscription.created':
    case 'subscription.updated':
    case 'subscription.cancelled':
      // Clear subscription cache
      if (data.customerRef) {
        await clearSubscriptionCache(data.customerRef);
      }
      
      // Update database
      await updateSubscriptionInDatabase(data);
      break;
    
    case 'payment.succeeded':
    case 'payment.failed':
      // Handle payment events
      await handlePaymentEvent(type, data);
      break;
    
    default:
      console.log('Unknown event type:', type);
  }
}

Express.js Complete Example

// routes/webhooks.ts
import express from 'express';
import { verifyWebhook } from '@solvapay/server';
import { clearSubscriptionCache } from '@solvapay/next';

const router = express.Router();

// Important: Use express.raw() to get raw body for signature verification
router.post(
  '/solvapay',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    try {
      const signature = req.headers['x-solvapay-signature'] as string;
      
      if (!signature) {
        return res.status(401).json({ error: 'Missing signature' });
      }
      
      const payload = req.body.toString();
      const verified = verifyWebhook(payload, signature, {
        secret: process.env.SOLVAPAY_WEBHOOK_SECRET!,
      });
      
      if (!verified) {
        return res.status(401).json({ error: 'Invalid signature' });
      }
      
      const event = JSON.parse(payload);
      await handleWebhookEvent(event);
      
      res.json({ received: true });
    } catch (error) {
      console.error('Webhook error:', error);
      res.status(500).json({ error: 'Webhook processing failed' });
    }
  }
);

async function handleWebhookEvent(event: any) {
  const { type, data } = event;
  
  switch (type) {
    case 'subscription.created':
    case 'subscription.updated':
    case 'subscription.cancelled':
      if (data.customerRef) {
        await clearSubscriptionCache(data.customerRef);
      }
      await updateSubscriptionInDatabase(data);
      break;
    
    case 'payment.succeeded':
    case 'payment.failed':
      await handlePaymentEvent(type, data);
      break;
  }
}

export default router;

Best Practices

1. Always Verify Signatures: Never process webhooks without verifying the signature.

2. Use Idempotency: Handle duplicate webhook deliveries gracefully.

3. Process Asynchronously: Process webhooks asynchronously to respond quickly.

4. Log Events: Log all webhook events for debugging and auditing.

5. Handle Errors Gracefully: Return appropriate status codes and log errors.

6. Clear Caches: Clear subscription caches when subscription events occur.

7. Update Database: Keep your database in sync with webhook events.

Testing Webhooks

Local Testing with ngrok

# Start your local server
npm run dev

# In another terminal, expose with ngrok
ngrok http 3000

# Use ngrok URL in SolvaPay dashboard webhook settings

Test Webhook Payload

// Test webhook locally
const testEvent = {
  type: 'subscription.created',
  data: {
    customerRef: 'user_123',
    subscriptionId: 'sub_123',
    planRef: 'pln_premium',
  },
  timestamp: new Date().toISOString(),
};

await handleWebhookEvent(testEvent);

Next Steps

• Error Handling Strategies - Handle webhook errors
• Next.js Integration Guide - Next.js webhook setup
• API Reference - Full API documentation