Stripe Events to SNS

AWS CDK Construct Library for sending Stripe events to SNS topics.

Overview

This library provides a CDK Construct for receiving Stripe webhook events through AWS EventBridge and sending notifications to SNS topics. It integrates with Stripe's partner event source to deliver real-time event notifications.

Key Features

EventBridge Integration: Receives events from Stripe's partner event source
Event Filtering: Processes only specified event types
SNS Notifications: Sends notifications to SNS with customizable message templates
Automatic IAM Setup: Automatically configures required permissions
TypeScript Support: Provides full type safety

Installation

npm install cdk-construct-stripe-events-to-sns

Getting Started

Step 1: Set up Stripe Event Destination & Amazon EventBridge

Before using this library, you need to set up Stripe Event Destinations and create a partner event bus in Amazon EventBridge. Follow these steps:

1.1: Enable Workbench

Go to your Stripe Dashboard
Navigate to Developer settings → Workbench
Enable Workbench if not already enabled

1.2: Create Event Destination

Open the Webhooks tab in Workbench
Click Create new destination
Select Account to listen to events from your own account
Choose the event types you want to receive
Select Amazon EventBridge as your destination type
Enter your AWS account ID and region
Click Create destination

1.3: Associate Partner Event Source

Go to AWS Management Console → EventBridge → Partner event sources
Select the region you chose in Step 1.2
Find the newly created partner event source (format: aws.partner/stripe.com/{UNIQUE_ID})
Click Associate with event bus
Select permissions and click Associate

1.4: Create EventBridge Rules

Navigate to EventBridge → Rules
Click Create Rule
Select your event bus from the dropdown
Under Event source, select AWS events or EventBridge partner events
Under Event Pattern, select EventBridge partners → Stripe
Choose event types or select All events
Configure your target (SNS, Lambda, etc.)
Click Create Rule

For detailed instructions, refer to the official Stripe documentation.

Step 2: Install and Use the Library

Now you can install and use the library in your CDK project:

npm install cdk-construct-stripe-events-to-sns

Usage

Basic Usage Example

import { Construct } from 'constructs';
import * as cdk from 'aws-cdk-lib';
import * as events from 'aws-cdk-lib/aws-events';
import * as sns from 'aws-cdk-lib/aws-sns';
import { StripeEventsToSns } from 'cdk-construct-stripe-events-to-sns';

export class MyStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // Reference Stripe's partner event source
    const eventBus = events.EventBus.fromEventBusName(
      this,
      'StripePartnerEventBus',
      'aws.partner/stripe.com/ed_xxxxxx'
    );

    // Create SNS topic
    const topic = new sns.Topic(this, 'StripeNotificationTopic', {
      topicName: 'StripeEventNotifications',
    });

    // Create Stripe event notification system
    new StripeEventsToSns(this, 'StripeEventNotifier', {
      eventBus,
      topic,
      eventTypes: ['payment_intent.succeeded', 'customer.created'],
      messageTemplate: EventField => ({
        version: '1.0',
        source: 'stripe',
        content: {
          textType: 'client-markdown',
          title: ':bell: Stripe Event Notification',
          description: [
            `**Event Type:** ${EventField.fromPath('$.detail-type')}`,
            `**Event ID:** ${EventField.fromPath('$.id')}`,
            `**Occurred At:** ${EventField.fromPath('$.time')}`,
            '',
            '**Details:**',
            `\`\`\`json\n${EventField.fromPath('$.detail')}\n\`\`\``,
          ].join('\n'),
        },
        metadata: {
          eventId: EventField.fromPath('$.id'),
          eventType: EventField.fromPath('$.detail-type'),
          eventTime: EventField.fromPath('$.time'),
        },
      }),
    });
  }
}

Slack Notification Configuration Example

// SNS topic for #shifter-activities channel
const snsTopicForShifterActivitiesChannel = new sns.Topic(
  this,
  'SnsTopicForShifterActivitiesChannel',
  {
    topicName: 'NotifyToShifterActivitiesChannel',
  }
);

// Stripe subscription creation event notification
new StripeEventsToSns(this, 'StripeSubscriptionCreatedToSNS', {
  eventBus,
  topic: snsTopicForShifterActivitiesChannel,
  eventTypes: ['customer.subscription.created'],
  messageTemplate: EventField => ({
    version: '1.0',
    source: 'custom',
    content: {
      textType: 'client-markdown',
      title: ':warning: Stripe Subscription Created Notification',
      description: [
        'A new subscription has been created',
        '',
        '📋 *Details:*',
        `• *Subscription ID:* ${EventField.fromPath('$.detail.data.object.id')}`,
        `• *Customer ID:* ${EventField.fromPath('$.detail.data.object.customer')}`,
        `• *Currency:* ${EventField.fromPath('$.detail.data.object.currency')}`,
        `• *Plan Name:* ${EventField.fromPath('$.detail.data.object.items.data[0].plan.nickname')}`,
        `• *Billing Interval:* ${EventField.fromPath('$.detail.data.object.items.data[0].plan.interval')}`,
        '',
        '🔗 *Stripe Dashboard:*',
        `• <https://dashboard.stripe.com/customers/${EventField.fromPath('$.detail.data.object.customer')}|👤 View Customer>`,
        `• <https://dashboard.stripe.com/subscriptions/${EventField.fromPath('$.detail.data.object.id')}|📋 View Subscription>`,
      ].join('\n'),
      nextSteps: [
        'Please review the new subscription details in the Stripe Dashboard',
        'Verify that customer billing information and plan are correctly configured',
      ],
    },
    metadata: {
      customerId: EventField.fromPath('$.detail.data.object.customer'),
      subscriptionId: EventField.fromPath('$.detail.data.object.id'),
      eventTime: EventField.fromPath('$.time'),
      eventSource: EventField.fromPath('$.source'),
    },
  }),
});

API Reference