Third-Party Integrations

Overview

Hub integrates with several third-party services to provide media storage, email notifications, and authentication. This guide covers configuration for all external integrations.

Cloudinary (Media Storage)

Cloudinary provides cloud-based image and video management for venue photos and user profile pictures.

Features

Image upload and storage
Automatic image optimization
Responsive image transformations
CDN delivery
Image format conversion (WebP, AVIF)

Setup

Create Cloudinary account

Sign up at cloudinary.com
Choose the free tier (includes 25GB storage and 25GB bandwidth)
Access your dashboard to get credentials

Get credentials

From your Cloudinary dashboard, note:

Cloud Name: Your unique cloud identifier
API Key: Public API key
API Secret: Private secret key

Configure environment

Add to your .env file:

.env

CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=123456789012345
CLOUDINARY_API_SECRET=your_secret_key_here

Create upload presets (optional)

In Cloudinary dashboard:

Go to Settings > Upload
Create upload presets for different image types:
- venue_photos - Max 2000x2000px, JPEG quality 85
- profile_pictures - Max 500x500px, crop to square

Configuration

CLOUDINARY_CLOUD_NAME

string

required

Your Cloudinary cloud nameExample: padelhub-media, hub-prodFound in your Cloudinary dashboard header.

CLOUDINARY_API_KEY

string

required

Cloudinary API key for authenticationFormat: 15-digit numberExample: 123456789012345

CLOUDINARY_API_SECRET

string

required

Cloudinary API secret for signing requests

Keep this secret secure. Never expose in client-side code or commit to version control.

Usage in Application

The backend uses Cloudinary for:

Venue Photos

Upload venue photo

CloudinaryAdapter cloudinary;

public String uploadVenuePhoto(MultipartFile file, Long venueId) {
    return cloudinary.uploadImage(
        file,
        Map.of(
            "folder", "venues/" + venueId,
            "transformation", List.of(
                Map.of("width", 2000, "height", 2000, "crop", "limit"),
                Map.of("quality", "auto:good")
            )
        )
    );
}

User Profile Pictures

Upload profile picture

public String uploadProfilePicture(MultipartFile file, String userId) {
    return cloudinary.uploadImage(
        file,
        Map.of(
            "folder", "users/" + userId,
            "transformation", Map.of(
                "width", 500,
                "height", 500,
                "crop", "fill",
                "gravity", "face"
            )
        )
    );
}

Image Transformations

Cloudinary URLs support on-the-fly transformations:

// Original
https://res.cloudinary.com/padelhub/image/upload/v1234/venues/1/photo.jpg

// Thumbnail (300x300)
https://res.cloudinary.com/padelhub/image/upload/w_300,h_300,c_fill/v1234/venues/1/photo.jpg

// WebP format
https://res.cloudinary.com/padelhub/image/upload/f_webp/v1234/venues/1/photo.jpg

// Optimized and responsive
https://res.cloudinary.com/padelhub/image/upload/w_auto,f_auto,q_auto/v1234/venues/1/photo.jpg

Best Practices

Use automatic format (f_auto) and quality (q_auto) for optimal delivery
Implement lazy loading for images
Use responsive image sizes with w_auto
Organize images in folders by entity type
Set up automatic backup and moderation rules

Brevo (Email Service)

Brevo (formerly Sendinblue) handles transactional emails for bookings, match requests, and notifications.

Features

Transactional email API
Email templates
Delivery tracking
SMTP relay
Free tier: 300 emails/day

Setup

Create Brevo account

Sign up at brevo.com
Verify your email address
Complete account setup

Generate API key

Go to Settings > API Keys
Click Generate a new API key
Give it a name (e.g., “Hub Production”)
Copy the generated key

Configure sender

Go to Settings > Senders
Add your sending email address (e.g., [email protected])
Verify domain ownership (add DNS records)

Configure environment

Add to your .env file:

.env

BREVO_API_KEY=xkeysib-abc123...
APP_MAIL_FROM=[email protected]

Configuration

BREVO_API_KEY

string

required

Brevo API key for sending transactional emailsFormat: xkeysib- followed by 64 charactersDevelopment: Use dummy-key-for-local to log emails without sending

Keep your API key secure. Rotate regularly and never commit to version control.

APP_MAIL_FROM

string

Sender email address for all transactional emailsDefault: [email protected]Requirements:

Must be verified in Brevo
Domain should have SPF and DKIM records configured
Use a no-reply address for transactional emails

Email Types

Hub sends the following transactional emails:

Booking confirmation

Sent when a booking is confirmed:

Booking details (venue, court, date/time)
Total cost
Cancellation policy
Link to view booking

Match request received

Sent when a user receives a match request:

Sender information
Match details (venue, date/time)
Accept/decline links

Match request accepted

Sent when a match request is accepted:

Confirmation message
Match details
Player contact information

Booking reminder

Sent 24 hours before a booking:

Reminder message
Booking details
Venue address and directions

Payment receipt

Sent after successful payment:

Payment amount
Payment method
Receipt number
Booking details

Usage in Application

The BrevoEmailSender component handles email delivery:

Send Email

@Component
public class BrevoEmailSender {
    
    @Value("${brevo.api.key}")
    private String apiKey;
    
    @Value("${app.mail.from}")
    private String from;
    
    public void send(String to, String subject, String htmlContent) {
        // Sends via Brevo API v3
        // POST https://api.brevo.com/v3/smtp/email
    }
}

Example usage:

Booking Confirmation Email

public void sendBookingConfirmation(Booking booking) {
    String html = templateEngine.process("booking-confirmation", 
        Map.of(
            "userName", booking.getUser().getName(),
            "venueName", booking.getResource().getVenue().getName(),
            "dateTime", booking.getStartTime(),
            "totalCost", booking.getTotalCost()
        )
    );
    
    brevoEmailSender.send(
        booking.getUser().getEmail(),
        "Booking Confirmed - " + booking.getResource().getVenue().getName(),
        html
    );
}

Email Templates

HTML email templates use Thymeleaf and are stored in:

backend/src/main/resources/templates/emails/
├── booking-confirmation.html
├── match-request.html
├── match-accepted.html
└── booking-reminder.html

Templates use Thymeleaf syntax for dynamic content insertion.

Development Mode

For local development without sending real emails:

.env.local

BREVO_API_KEY=dummy-key-for-local

With the dummy key, emails are logged to console instead of sent:

INFO : Would send email to [email protected]
INFO : Subject: Booking Confirmed
INFO : Body: <html>...</html>

Monitoring

Brevo Dashboard:

View email delivery statistics
Check bounce and spam rates
Monitor API usage
Review email logs

Application Logs:

log.info("Email sent via Brevo API to {}", to);

Auth0 (Authentication)

Auth0 integration is covered in detail in the Authentication Configuration guide.

Quick Reference

AUTH0_ISSUER

string

required

Auth0 domain for JWT validationExample: https://padelhub.eu.auth0.com/

AUTH0_AUDIENCE

string

required

Auth0 API audience identifierExample: https://api.padelhub.com

Learn more about Auth0 configuration →

Integration Health Checks

Testing Cloudinary

curl -X POST "https://api.cloudinary.com/v1_1/${CLOUDINARY_CLOUD_NAME}/image/upload" \
  -F "[email protected]" \
  -F "api_key=${CLOUDINARY_API_KEY}" \
  -F "timestamp=$(date +%s)" \
  -F "signature=YOUR_SIGNATURE"

Testing Brevo

curl -X POST "https://api.brevo.com/v3/smtp/email" \
  -H "api-key: ${BREVO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": {"email": "[email protected]"},
    "to": [{"email": "[email protected]"}],
    "subject": "Test Email",
    "htmlContent": "<p>Test message</p>"
  }'

Testing Auth0

curl "${AUTH0_ISSUER}.well-known/jwks.json"

Security Considerations

Rotate API keys regularly

Set up a schedule to rotate all API keys every 90 days.

Use environment-specific keys

Never share keys between development, staging, and production.

Monitor usage

Set up alerts for unusual API usage patterns:

Sudden spike in requests
High error rates
Quota approaching limits

Implement rate limiting

Protect against abuse:

Limit image uploads per user per hour
Throttle email sending
Implement CAPTCHA for public endpoints

Store secrets securely

Use secrets management:

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
Google Secret Manager

Cost Management

Cloudinary

Free Tier:

25 GB storage
25 GB monthly bandwidth
25 credits/month

Optimization Tips:

Use automatic format and quality (f_auto, q_auto)
Enable lazy loading
Implement image size limits
Delete unused images regularly

Brevo

Free Tier:

300 emails/day
Unlimited contacts

Optimization Tips:

Batch notification emails
Implement user email preferences
Use email templates efficiently
Monitor bounce rates

Auth0

Free Tier:

7,000 monthly active users
Unlimited logins

Optimization Tips:

Implement token refresh to reduce authentication calls
Use appropriate token expiration times
Cache user profile data

Troubleshooting

Cloudinary upload fails

Error: Invalid API keySolutions:

Verify CLOUDINARY_API_KEY and CLOUDINARY_API_SECRET are correct
Check API key hasn’t been revoked
Ensure cloud name matches your account

Emails not sending

Error: Unauthorized or emails not deliveredSolutions:

Verify BREVO_API_KEY is valid
Check sender email is verified in Brevo
Review Brevo dashboard for blocked sends
Check DNS records (SPF, DKIM)

Auth0 token validation fails

Error: Invalid issuer or Invalid audienceSolutions:

Verify AUTH0_ISSUER includes trailing slash
Ensure AUTH0_AUDIENCE matches Auth0 API identifier
Check Auth0 API is enabled

High API costs

Issue: Approaching quota limitsSolutions:

Review usage patterns in dashboards
Implement caching where appropriate
Optimize image sizes and formats
Consolidate email notifications

Next Steps

Environment Setup

Complete environment configuration

Deployment Guide

Deploy to production

API Reference

Explore API endpoints

Backend Modules

Understand backend architecture

Get Started

Core Features

User Guides

Configuration

​Overview

​Cloudinary (Media Storage)

​Features

​Setup

​Configuration

​Usage in Application

​Venue Photos

​User Profile Pictures

​Image Transformations

​Best Practices

​Brevo (Email Service)

​Features

​Setup

​Configuration

​Email Types

​Usage in Application

​Email Templates

​Development Mode

​Monitoring

​Auth0 (Authentication)

​Quick Reference

​Integration Health Checks

​Testing Cloudinary

​Testing Brevo

​Testing Auth0

​Security Considerations

​Cost Management

​Cloudinary

​Brevo

​Auth0

​Troubleshooting

​Next Steps

Environment Setup

Deployment Guide

API Reference

Backend Modules

Build docs developers (and LLMs) love

Overview

Cloudinary (Media Storage)

Features

Setup

Configuration

Usage in Application

Venue Photos

User Profile Pictures

Image Transformations

Best Practices

Brevo (Email Service)

Features

Setup

Configuration

Email Types

Usage in Application

Email Templates

Development Mode

Monitoring

Auth0 (Authentication)

Quick Reference

Integration Health Checks

Testing Cloudinary

Testing Brevo

Testing Auth0

Security Considerations

Cost Management

Cloudinary

Brevo

Auth0

Troubleshooting

Next Steps