Backend: Implement Strava webhook registration and event processing

[Copilot]

Overview

Implements the backend infrastructure for Strava webhook integration, enabling real-time activity synchronization as outlined in issue #59. This replaces the need for manual bulk imports by automatically processing activity create, update, and delete events from Strava.

What's New

Database Schema

Added webhook tracking fields to support subscription management:

• users.strava_webhook_subscription_id - Stores Strava's subscription ID
• users.webhook_verify_token - Token for webhook verification
• plans.webhook_enabled - Boolean flag to enable/disable webhooks per plan

Webhook Endpoints

Verification Endpoint (GET /webhooks/strava)

• Handles Strava's webhook verification challenge
• Validates verify token before responding with challenge
• Required for initial webhook subscription setup

Event Endpoint (POST /webhooks/strava)

• Receives activity events from Strava (create, update, delete)
• Queues background jobs for asynchronous processing
• Returns 200 OK immediately to acknowledge receipt

Core Components

StravaWebhookService (app/services/strava_webhook_service.rb)
Manages webhook subscription lifecycle through Strava's Push Subscriptions API:

# Create subscription
StravaWebhookService.create_subscription(user, "https://example.com/webhooks/strava")

# Delete subscription
StravaWebhookService.delete_subscription(user)

# List/view subscriptions
StravaWebhookService.list_subscriptions

ProcessStravaWebhookJob (app/jobs/process_strava_webhook_job.rb)
Processes webhook events asynchronously:

• Fetches full activity details from Strava API using user's access token
• Creates new activities on create events
• Updates existing activities on update events
• Deletes activities on delete events
• Handles missing users and API errors gracefully

Webhooks::StravaController (app/controllers/webhooks/strava_controller.rb)

• Skips authentication and CSRF protection (required for Strava's external requests)
• Validates webhook events before processing
• Uses consistent verify token for security

Implementation Details

Strava API Constraints

Strava allows only one webhook subscription per application (not per user). The implementation handles this by:

• Storing subscription details on a user record for token management
• Processing events for all users based on owner_id in webhook payload
• Using the user's strava_id to route events to the correct account

Security

• Webhook verification using secret verify token
• Credentials managed via Rails credentials or environment variables
• HTTPS required for all webhook endpoints
• No secrets hardcoded in source code

Testing

Comprehensive test coverage with VCR cassettes for all HTTP interactions:

• 7 controller tests - Webhook verification and event handling
• 6 job tests - Activity creation, updates, and deletion
• 7 service tests - Subscription management (create, delete, list, view)
• All 43 tests passing with 1100 assertions

Documentation

Added complete setup and usage guide in docs/STRAVA_WEBHOOKS.md covering:

• Architecture overview and component descriptions
• Step-by-step configuration instructions
• Code examples for common operations
• Troubleshooting guide for common issues
• Security considerations

Future Work

This PR provides the backend foundation. Future PRs will add:

• UI components for enabling webhooks during plan creation
• Activity matching algorithm (date, distance, type matching)
• User interface for managing unmatched activities

Closes #60 (Backend portion of #59)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Backend: Strava webhook registration and configuration</issue_title>
<issue_description>See parent issue #59 for overall context.

Create webhook endpoint, register subscriptions, manage Strava API calls.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #97

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.