Correlate

cor·re·late, verb | ˈkôrəˌlāt | to have a mutual relationship or connection, in which one thing affects or depends on another.

Correlate is a service that listens for webhook events and, in response to those events, sends notification emails about orders. It can optionally store order information in a database, allowing you to query and make connections between the data later on (or, one could say correlations). e.g. Which product variant has the most sales? Which day typically has the most sales?

Features

• Webhook Handling: Processes Stripe checkout session events
• Checkout Session Creation: Creates Stripe checkout sessions for payment processing
• Email Notifications: Sends confirmation emails for successful orders
• Optional Database Integration: Stores order information using a MySQL database (can be disabled)
• Containerized Deployment: Easy deployment with Docker

Installation

Prerequisites

• MSRV is Rust 1.82
• Stripe account with webhook configuration
• MariaDB/MySQL database (optional, only if database integration is enabled)

Using Cargo

# Clone the repository
git clone https://code.orbitsolutions.dev/orb-it-solutions/correlate.git
cd correlate

# Build the project (with database support enabled by default)
cargo build --release

# Build without database support
cargo build --release --no-default-features

# Run the application
cargo run --release

Using Docker

# Build the Docker image (with database support by default)
docker build -t correlate .

# Build the Docker image without database support
docker build --build-arg WITH_DATABASE=false -t correlate:no-db .

# Run the container with database support
docker run -p 8000:8000 -p 25:25 \
  -e CORRELATE_STRIPE_SECRET=your_stripe_secret_key \
  -e CORRELATE_EMAIL_SENDER=your_sender_email \
  -e CORRELATE_EMAIL_RECIPIENT=your_recipient_email \
  -e CORRELATE_PRODUCTS='[{name="Product Name",sku="product-sku",price="price_12345"},{name="Another Product",sku="another-sku",price="price_67890"}]' \
  -e CORRELATE_DATABASES={db_name={url="mysql://user:password@hostname:3306/db_name"}} \
  correlate

# Run the container without database support
docker run -p 8000:8000 -p 25:25 \
  -e CORRELATE_STRIPE_SECRET_KEY=your_stripe_secret_key \
  -e CORRELATE_EMAIL_SENDER=your_sender_email \
  -e CORRELATE_EMAIL_RECIPIENT=your_recipient_email \
  -e CORRELATE_PRODUCTS='[{name="Product Name",sku="product-sku",price="price_12345"},{name="Another Product",sku="another-sku",price="price_67890"}]' \
  correlate:no-db

Dependencies

The project uses the following key dependencies:

• rocket: Web framework for handling HTTP requests and responses
• lettre: Email sending library
• tera: Template engine for generating email content
• validator: Data validation library
• ureq: HTTP client for making API calls to Stripe
• thiserror: Error handling utilities

Optional Dependencies

These dependencies are only required if database integration is enabled:

• diesel: ORM and query builder
• diesel_migrations: Database migration tools
• rocket_db_pools: Database connection pooling
• mysqlclient-sys: MySQL client library

Configuration

Feature Flags

To build without database support:

cargo build --no-default-features

To explicitly enable database support:

cargo build --features database

Environment Variables

Rocket.toml Configuration

You can also configure the application using a Rocket.toml file:

[default.stripe]
secret_key = "sk_test_your_test_key"

[default.email]
sender = "noreply@example.com"
recipient = "orders@example.com"
smtp_relay_host = "smtp.example.com"
smtp_relay_port = 2525
smtp_username = "username"
smtp_password = "password"

# Product configuration for checkout session creation
default.products = [
  { name = "Product Name", sku = "product-sku", price = "price_12345" },
  { name = "Another Product", sku = "another-sku", price = "price_67890" }
]

# Only needed when database feature is enabled
[default.databases]
database_name = { url = "mysql://user:password@hostname:3306/database_name" }

Usage

Setting Up Stripe Webhooks

1. Go to the Stripe Dashboard
2. Create a new webhook endpoint with your server URL (e.g., https://your-domain.com/)
3. Select the checkout.session.completed event to listen for
4. Copy the webhook signing secret to use with the application

API Endpoints

• GET /: Returns application information
• POST /: Webhook endpoint for Stripe events
• POST /checkout: Endpoint to create a new Stripe checkout session

Example: Creating a Checkout Session

To create a new checkout session for payment processing:

1. Configure products in your Rocket.toml file or environment variables (see Configuration section)
2. Send a POST request to the /checkout endpoint with the following JSON payload:

{
  "success_url": "https://your-domain.com/success",
  "submission_url": "https://your-domain.com/cancel",
  "items": [
    {
      "name": "Product Name",
      "sku": "product-sku",
      "quantity": 1
    }
  ]
}

3. The API will validate the request, look up the Stripe price ID for each product, and create a checkout session via Stripe's API
4. If successful, it will return a status 200 with the Stripe checkout URL

Note: The name and sku in your request must match entries in your product configuration. The service will use these to find the corresponding Stripe price ID.

Example: Processing a Webhook

When a successful checkout is completed in Stripe, the webhook will:

1. Receive the event data
2. Validate the payment was successful
3. Retrieve order information
4. Send a confirmation email to the customer
5. Return a success status

Database Schema

When the database feature is enabled, the application uses the following tables:

• stripe_customers: Stores customer information from Stripe events
• users: Basic user account information (if user accounts are enabled)

Note: The database integration is optional. If you don't want to store order information, you can build the application without database support using --no-default-features.

Development

Setting Up Development Environment

With Database Support (Default)

To create a local mysql/mariadb database named correlate you would use diesel to run the commands below:

# Install development dependencies
cargo install diesel_cli --no-default-features --features mysql

# Set up the database
diesel setup --database-url=mysql://root:root@localhost:3306/correlate
diesel migration run

# Set up the database without TLS support
diesel setup --database-url=mysql://root:root@localhost:3306/correlate?ssl_mode=DISABLED
diesel migration run

# Run in development mode with database support
cargo run

Without Database Support

If you don't need database integration:

# Run in development mode without database support
cargo run --no-default-features

Running Tests

cargo test

License

This project is licensed under the MIT License - see the LICENSE file for details.