OpenSaaS支付集成Webhook路径变更说明

OpenSaaS作为一款开源SaaS框架，在支付集成功能上经历了重要的接口路径调整。本文将为开发者详细解析这一变更的技术背景及影响范围。

变更内容

在早期版本的OpenSaaS中，Stripe支付回调的默认Webhook路径为：

/stripe-webhook

而在最新版本中，该路径已统一调整为：

/payments-webhook

变更背景

此次路径调整主要基于以下技术考量：

1. 支付服务扩展性：随着Lemon Squeezy等新型支付服务的集成，框架需要更通用的支付端点命名规范

2. 接口标准化：统一路径命名有利于开发者构建一致的支付处理逻辑

3. 版本兼容性：新版本保持向后兼容，但推荐使用新路径进行开发

影响范围

• 新项目：使用最新模板创建的项目默认采用/payments-webhook路径
• 已有项目：升级框架版本后，原有/stripe-webhook路径仍可继续使用
• 开发环境：本地测试时需注意CLI工具的版本对应关系

最佳实践建议

1. 新建项目时直接使用/payments-webhook路径
2. 现有项目升级时，建议逐步迁移到新路径
3. 测试环境配置需与运行版本严格对应
4. 文档参考应以项目实际版本为准

技术实现细节

框架内部通过中间件层实现了路径的版本适配，开发者可以通过配置项指定使用的Webhook路径。对于需要同时支持多支付服务的场景，建议采用路由分发策略，在统一入口处根据支付类型进行请求分发。

此次变更体现了OpenSaaS框架在支付模块设计上向更灵活、更可扩展的架构演进，为开发者提供了更好的支付服务集成体验。