Twenty Stripe App

Stripe integration for Twenty CRM - webhook handler for payment events and customer synchronization.

Installation

npm install -g twenty-stripe-app

Usage

Setup Environment Variables

Create a .env file:

# Stripe Configuration
STRIPE_PUBLISHABLE_KEY=pk_test_51TIOoUCb7X6XmwFfUsoaGZL3FZ3sQS1iwXg0lfiLxIlR6Hlo1m2XOYdaEoEySGcrFaxNMlDgXAWy3APDIAh9FngX003jFn5Wf6
STRIPE_SECRET_KEY=sk_test_51TIOoUCb7X6XmwFfgDjbQC8giq0vhmFeZoIaY2FI84Svwox9BkShza2cDvBDKsXK4Z8HZcx1zoOGgOH4klKeY2YT00DLxIQjxE
STRIPE_WEBHOOK_SECRET=your_stripe_webhook_secret_here

# Twenty CRM Configuration
TWENTY_URL=http://localhost:3000
TWENTY_API_KEY=your_twenty_api_key_here

# Server Configuration
PORT=3002
NODE_ENV=development

Stripe Webhook Setup

1. Start ngrok for local development:

ngrok http 3002

2. Configure webhook in Stripe Dashboard:

• Go to: https://dashboard.stripe.com/test/webhooks
• Add endpoint: https://your-ngrok-url.ngrok.io/stripe/webhook
• Select events: payment_intent.succeeded, payment_intent.payment_failed, customer.created, invoice.payment_succeeded, invoice.payment_failed, charge.succeeded
• Copy the signing secret to STRIPE_WEBHOOK_SECRET

Start the App

# Development
npm run dev

# Production
npm run build
npm start

Features

• Payment Event Processing - Handle Stripe payment events
• Customer Synchronization - Create/Update people in Twenty CRM
• Deal Creation - Automatically create deals from payments
• Webhook Verification - Secure webhook signature verification
• Error Handling - Comprehensive error logging and recovery
• Health Checks - Monitor application status

API Endpoints

Stripe Webhook

POST /stripe/webhook

Receives and processes Stripe webhook events.

Health Check

GET /health

Returns application status and configuration.

Stripe Configuration

GET /stripe/config

Returns Stripe publishable key and webhook configuration.

Logic Functions

HTTP Route: POST /stripe/webhook

• Verifies Stripe webhook signature
• Processes payment events
• Creates/updates deals in Twenty CRM
• Synchronizes customer data

Supported Events

• payment_intent.succeeded → Create/update deal
• payment_intent.payment_failed → Update deal status
• customer.created → Create person in Twenty
• invoice.payment_succeeded → Create/update deal
• invoice.payment_failed → Update deal status
• charge.succeeded → Create note with charge details

Acceptance Criteria

✅ Stripe Webhook Integration

• Webhook Verification: HMAC signature verification
• Event Processing: All supported events handled
• Error Recovery: Graceful error handling and logging

✅ Deal Creation Flow

• Payment Succeeded: Creates deal with amount and currency
• Payment Failed: Updates deal status to closed-lost
• Customer Link: Links deals to people via Stripe customer ID

✅ Customer Synchronization

• Customer Created: Creates person in Twenty CRM
• Data Mapping: Email, phone, name fields mapped
• Metadata Support: Stripe metadata preserved

Webhook Event Mapping

| Stripe Event | Twenty CRM Action | Details | |-------------|------------------|---------| | payment_intent.succeeded | Create/Update Deal | Amount, currency, stage=closed-won | | payment_intent.payment_failed | Update Deal | Stage=closed-lost | | customer.created | Create Person | Email, phone, name, stripeCustomerId | | invoice.payment_succeeded | Create/Update Deal | Amount, currency, stage=closed-won | | invoice.payment_failed | Update Deal | Stage=in-progress | | charge.succeeded | Create Note | Charge details and metadata |

Development

Local Development

# Clone repository
git clone https://github.com/deliveredbyai/twenty-stripe-app.git
cd twenty-stripe-app

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your credentials

# Start development server
npm run dev

Testing Webhooks

# Start ngrok
ngrok http 3002

# Test webhook with Stripe CLI
stripe listen --forward-to localhost:3002/stripe/webhook

# Trigger test events
stripe trigger payment_intent.succeeded
stripe trigger customer.created

Test Cards

Successful payment: 4242 4242 4242 4242
Payment failed: 4000 0000 0000 0002
3D Secure required: 4000 0025 0000 3155

Architecture

Stripe API ←→ twenty-stripe-app ←→ Twenty CRM API
     ↓              ↓                    ↓
  Webhooks      Express Server       Database
  Events        Stripe SDK          People/Deals
  Signatures    Webhook Handler     Notes/Metadata

Error Handling

• Webhook Verification: HMAC signature validation
• API Errors: Automatic retry with exponential backoff
• Data Validation: Input sanitization and validation
• Logging: Comprehensive error logging and debugging

Security

• Webhook Verification: Stripe signature verification
• Environment Variables: Sensitive data in environment
• HTTPS Required: Production HTTPS enforcement
• Input Validation: Request body validation

Monitoring

Health Check

curl http://localhost:3002/health

Stripe Configuration

curl http://localhost:3002/stripe/config

Logs

• Application logs to console
• Webhook event logging
• Error details for debugging
• Stripe API interaction logs

Troubleshooting

Common Issues

"Webhook signature verification failed"

• Check STRIPE_WEBHOOK_SECRET in .env
• Verify webhook secret from Stripe Dashboard
• Ensure raw body is preserved for verification

"Twenty CRM connection failed"

• Check TWENTY_URL and TWENTY_API_KEY
• Verify Twenty CRM is running
• Test API connection manually

"Deal creation failed"

• Check person creation logic
• Verify Twenty CRM API permissions
• Check webhook event data structure

"Ngrok URL not working"

• Ensure ngrok is running on correct port
• Check Stripe webhook URL configuration
• Verify firewall allows ngrok connections

Support

• Report Issues
• Discussions

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create feature branch
3. Make your changes
4. Run tests
5. Submit pull request

Acknowledgments

• Stripe Node.js SDK - Official Stripe SDK
• Twenty CRM - Open-source CRM
• Express.js - Web Framework
• Twenty SDK - CRM SDK