如何接收Stripe发往Wix的Webhook并提取订单及商品信息

前置配置 #

• Wix侧开启Velo开发模式，在后端目录新建http-functions.js文件作为Webhook接收端点，站点发布后会自动生成可公网访问的接口地址。
• Stripe后台进入Webhook配置页，新增端点，地址填上述Wix生成的接口地址，监听事件仅勾选checkout.session.completed，注意不要勾选无关事件，减少无效推送占用资源，生成签名密钥后保存到Wix的环境变量中，禁止硬编码在代码里。

核心字段提取逻辑 #

注意checkout.session.completed事件的默认推送payload不会携带完整商品明细，也不会自动关联你Wix侧的订单编号，需要按以下规则配置：

1. 订单编号提取：你在前端/后端创建Stripe Checkout Session时，必须把Wix侧预生成的订单编号传入client_reference_id字段，Webhook推送到达后，直接从data.object.client_reference_id字段即可取到对应订单编号。如果已经有存量逻辑用了自定义字段，也可以从data.object.metadata里取预存的订单ID，优先用client_reference_id字段，这是Stripe预留的商户侧订单标识字段，不会和其他系统字段冲突。
2. 商品信息提取：不要尝试直接从session payload里解析商品数据，字段不全还容易因为结构变更出错。接收到合法的事件后，用Stripe服务端SDK传入当前session ID，调用checkout.sessions.listLineItems接口拉取全量商品行，返回结果里包含每个商品的名称、SKU、购买数量、单价、实付分摊金额、关联折扣信息，直接用即可。

可直接复用的核心代码 #

// 代码存放路径：backend/http-functions.js
import Stripe from 'stripe';
// 从Wix环境变量读取Stripe密钥，不要硬编码
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

export async function post_stripeCheckoutWebhook(request) {
  const signature = request.headers['stripe-signature'];
  let event;

  try {
    // 校验请求签名，拦截伪造的推送请求
    event = stripe.webhooks.constructEvent(
      await request.text(),
      signature,
      process.env.STRIPE_WEBHOOK_SIGNING_SECRET
    );
  } catch (err) {
    return { statusCode: 400, body: `Invalid request: ${err.message}` };
  }

  // 仅处理结账完成事件
  if (event.type === 'checkout.session.completed') {
    const sessionData = event.data.object;
    // 提取Wix侧订单编号
    const wixOrderId = sessionData.client_reference_id;
    // 拉取全量购买商品明细
    const productList = await stripe.checkout.sessions.listLineItems(sessionData.id, {
      limit: 100 // 单次最多拉100个商品，单订单商品超量的话加分页逻辑即可
    });

    // 后续业务逻辑写在这里：比如更新Wix订单状态、写入商品明细、扣减库存、触发发货通知
    // 注意：耗时逻辑请放到Wix异步任务中执行，不要阻塞Webhook响应
  }

  // 必须在2秒内返回200状态码，否则Stripe会持续重复推送该事件
  return { statusCode: 200, body: JSON.stringify({ code: 0, msg: 'success' }) };
}

常见踩坑点 #

• 所有Webhook逻辑必须放在Wix后端执行，不要在前端接口接收Stripe推送，会导致签名密钥泄露，产生伪造请求风险。
• 接口返回200的耗时不能超过2秒，库存更新、邮件通知这类耗时操作请丢到Wix异步任务队列处理，避免重复推送。
• 如果订单使用了优惠券、积分抵扣，listLineItems返回的商品金额已经是折后分摊的实付金额，不需要额外计算。
• 测试阶段可以用Stripe的Webhook测试功能发模拟事件，不要用真实支付逐笔测，节省调试时间。

内容的提问来源于stack exchange，提问作者alch_coder