Stripe Webhooks

​

Overview

​

Endpoint

POST /api/stripe/webhooks

​

Authentication

​

Signature Verification

const event = stripe.webhooks.constructEvent(
  await (await req.blob()).text(),
  req.headers.get("stripe-signature") as string,
  process.env.STRIPE_WEBHOOK_SECRET as string
);

​

Configuration

​

Environment Variables

​

Setup in Stripe Dashboard

1. Go to Developers → Webhooks in your Stripe Dashboard
2. Click Add endpoint
3. Enter your webhook URL: https://your-domain.com/api/stripe/webhooks
4. Select the events to listen to (see Supported Events)
5. Copy the webhook signing secret and add it to your environment variables

​

Supported Events

​

checkout.session.completed

• Recurring subscription checkouts (mode: subscription)
• One-time payment checkouts for lifetime plans (mode: payment)
• Referral code application from session metadata

• Creates or updates subscription record in database
• Sets subscription plan based on product name
• Configures billing interval (monthly, quarterly, or lifetime)
• Applies referral codes if present in metadata

​

customer.subscription.created

• Creates subscription record for new customer
• Sets initial status (TRIAL or ACTIVE)
• Records trial period if applicable
• Links subscription to user account

​

customer.subscription.updated

• Updates subscription status in database
• Handles subscription cancellation scheduling
• Records cancellation feedback if provided
• Updates billing period and plan information

• active → ACTIVE
• trialing → TRIAL
• past_due → PAST_DUE
• incomplete → PAYMENT_PENDING
• incomplete_expired → EXPIRED
• canceled → CANCELLED
• unpaid → UNPAID

​

customer.subscription.deleted

• Updates subscription status to CANCELLED
• Sets plan to FREE
• Records final end date

​

invoice.payment_failed

• Updates subscription status to PAYMENT_FAILED
• Allows retry logic to handle payment recovery

​

payment_intent.succeeded

• Logs successful payment
• Used for monitoring and debugging

​

payment_intent.payment_failed

• Logs payment failure details
• Records error message for debugging

​

customer.subscription.trial_will_end

• Can be used to send reminder emails to customers
• Currently logged for monitoring

​

Request Format

​

Headers

Content-Type: application/json
Stripe-Signature: t=1234567890,v1=signature_hash,v0=fallback_signature

​

Body

{
  "id": "evt_1234567890",
  "object": "event",
  "api_version": "2023-10-16",
  "created": 1234567890,
  "type": "customer.subscription.updated",
  "data": {
    "object": {
      "id": "sub_1234567890",
      "customer": "cus_1234567890",
      "status": "active",
      "plan": {
        "id": "price_1234567890",
        "product": "prod_1234567890",
        "nickname": "Pro Plan"
      },
      "current_period_end": 1234567890,
      "trial_end": null,
      "cancel_at_period_end": false
    }
  }
}

​

Response Format

​

Success Response

{
  "message": "Received"
}

​

Error Responses

​

Invalid Signature

{
  "message": "Webhook Error: [error details]"
}

​

Processing Error

{
  "message": "Webhook handler failed"
}

​

Subscription Plans

​

Recurring Subscriptions

• Monthly plans: interval: month, interval_count: 1
• Quarterly plans: interval: month, interval_count: 3
• Plan name is derived from Stripe product name (uppercase)

​

Lifetime Plans

• One-time payment mode
• End date set to 100 years in the future
• interval: lifetime

​

Referral Code Handling

// In checkout session creation
metadata: {
  referral_code: "REF123"
}

1. Retrieves the referral by slug
2. Validates the referral doesn’t belong to the purchasing user
3. Adds user to referral list if not already present
4. Logs application success or errors

​

Security Considerations

​

Best Practices

1. Signature Verification: Always verify the stripe-signature header
2. HTTPS Only: Only accept webhooks over HTTPS in production
3. Secret Rotation: Regularly rotate webhook signing secrets
4. Idempotency: Handle duplicate events gracefully (Stripe may send the same event multiple times)
5. Timeout Protection: Respond to webhooks within 10 seconds to avoid retries

​

Environment Security

# .env.example
STRIPE_WEBHOOK_SECRET='your_stripe_webhook_secret_here'
STRIPE_SECRET_KEY='your_stripe_secret_key_here'

​

Testing

​

Local Testing with Stripe CLI

1. Install the Stripe CLI:
   # macOS
   brew install stripe/stripe-cli/stripe
   
   # Linux
   wget https://github.com/stripe/stripe-cli/releases/latest/download/stripe_linux_amd64.tar.gz
   tar -xvf stripe_linux_amd64.tar.gz
   
2. Login to Stripe:
   stripe login
   
3. Forward webhooks to your local server:
   stripe listen --forward-to localhost:3000/api/stripe/webhooks
   
4. Copy the webhook signing secret displayed and add it to your .env.local:
   STRIPE_WEBHOOK_SECRET=whsec_...
   
5. Trigger test events:
   # Test subscription created
   stripe trigger customer.subscription.created
   
   # Test checkout completed
   stripe trigger checkout.session.completed
   
   # Test payment failed
   stripe trigger invoice.payment_failed
   

​

Testing in Development

1. Go to Developers → Webhooks
2. Click on your endpoint
3. Click Send test webhook
4. Select an event type
5. Optionally customize the event data
6. Click Send test webhook

​

Monitoring Webhook Delivery

1. Go to Developers → Webhooks
2. Click on your endpoint
3. View recent deliveries with response codes and timing
4. Click on individual events to see request/response details

​

Troubleshooting

​

Common Issues

​

Signature Verification Failed

• Verify STRIPE_WEBHOOK_SECRET matches the secret in Stripe Dashboard
• Ensure you’re using the correct endpoint URL
• Check that the request hasn’t been modified by middleware

​

Database Update Failed

• Verify DATABASE_URL is correctly configured
• Check database connection and permissions
• Review application logs for detailed error messages
• Ensure user exists in database before subscription creation

​

Events Not Received

• Verify endpoint URL is accessible from the internet
• Check firewall rules allow Stripe IPs
• Ensure webhook endpoint is configured in Stripe Dashboard
• Review server logs for incoming requests

​

Duplicate Events

• Stripe may send duplicate events, implement idempotency checks
• Use event ID (event.id) to track processed events
• Consider implementing event deduplication logic

​

Rate Limits

• Timeout: 10 seconds (respond within this time to avoid retries)
• Retries: Failed webhooks are retried with exponential backoff for up to 3 days
• Order: Events may arrive out of order; use timestamps to handle this

​

Code Example

export async function POST(req: Request) {
  // 1. Verify webhook signature
  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      await (await req.blob()).text(),
      req.headers.get("stripe-signature") as string,
      process.env.STRIPE_WEBHOOK_SECRET as string
    );
  } catch (err) {
    return NextResponse.json(
      { message: `Webhook Error: ${err}` },
      { status: 400 }
    );
  }

  // 2. Check if event type is permitted
  const permittedEvents = [
    "checkout.session.completed",
    "customer.subscription.created",
    "customer.subscription.updated",
    "customer.subscription.deleted",
    "invoice.payment_failed",
    "payment_intent.succeeded",
    "payment_intent.payment_failed",
    "customer.subscription.trial_will_end"
  ];

  if (!permittedEvents.includes(event.type)) {
    return NextResponse.json({ message: "Received" }, { status: 200 });
  }

  // 3. Process event based on type
  try {
    switch (event.type) {
      case "checkout.session.completed":
        // Handle subscription or one-time payment
        break;
      case "customer.subscription.updated":
        // Update subscription status
        break;
      // ... other cases
    }
  } catch (error) {
    return NextResponse.json(
      { message: "Webhook handler failed" },
      { status: 500 }
    );
  }

  // 4. Return success response
  return NextResponse.json({ message: "Received" }, { status: 200 });
}

​

Related Resources

• Stripe Webhook Documentation
• Stripe API Reference
• Stripe CLI Documentation
• Webhook Security Best Practices