如何通过后台作业可靠地处理 Stripe 的 Webhook 请求

步骤3：发送购买确认邮件

await step.run("send-purchase-confirmation", async () => {
  await sendEmail({
    to: user.email,
    subject: `您的购买已确认！`,
    template: createElement(PurchaseConfirmationEmail, {
      amount: purchase.amount,
      currency: purchase.currency,
      customerEmail: user.email,
    }),
  });
});

这封邮件是专门发送给客户的确认通知。它与管理员通知（步骤4）是分开处理的，因为这两项操作是相互独立的。即使管理员的通知邮件发送失败，客户仍然应该能够收到购买确认邮件。

sendEmail函数实际上会使用Resend服务来发送邮件。如果Resend返回错误代码500，这个步骤会自动重试。不过由于步骤2（数据跟踪）已经完成并且被标记为检查点，因此步骤2不会被重新执行。

步骤4：发送管理员通知

await step.run("send-admin-notification", async () => {
  const adminEmail = process.env ADMIN_EMAIL;
  if (!adminEmail) return;

  await sendEmail({
    to: adminEmail,
    subject: `有新优惠信息：${user.email}`,
    template: createElement(AdminPurchaseNotificationEmail, { /* ... */ }),
  });
});

管理员通知系统与面向客户的操作是完全独立的。将它们分开处理，意味着其中一个环节出现故障也不会影响到另一个环节的正常运行。

步骤5：授予GitHub访问权限

const collaboratorResult = await step.run(
  "add-github-collaborator",
  async () => {
    return addCollaborator(user.githubUsername!);
  }
);

这一步骤最有可能出现故障。GitHub的API存在速率限制，可能会超时，而且用户的GitHub用户名也可能无效。

由于将这一操作单独列为一个步骤，因此如果GitHub API出现故障，也不会导致确认邮件（步骤3）或管理员通知（步骤4）被重新发送。因为这些步骤已经在之前的环节中完成了相应的处理。

请注意，在这个步骤之前会进行提前判断：如果用户没有GitHub用户名，那么在步骤4执行完毕后，函数会立即返回结果。只有当用户确实拥有GitHub账户时，后续的步骤才会继续执行。

步骤6：跟踪GitHub访问权限的状态

await step.run("track-github-access", async () => {
  await trackServerEvent(userId, "github_access_granted", {
    tier,
    github_username: user.githubUsername,
    invitation_status: collaboratorResult.status,
  });
});

这一操作会使用步骤5中获得的collaboratorResult数据。由于step.run()会缓存函数返回的结果，因此即使步骤5和步骤6之间的执行过程被中断后又重新开始，collaboratorResult.status的值仍然可以正常使用。

步骤7：更新购买记录

await step.run("update-purchase-record", async () => {
  await db
    .update(purchases)
    .set({
      githubAccessGranted: true,
      githubInvitationId: collaboratorResult.status,
     .updated: new Date(),
    })
    .where(eq(purchases.stripeCheckoutSessionId, sessionId));
});

数据库的更新操作要等到GitHub访问权限被确认之后才能进行。只有当邀请成功后，才会将githubAccessGranted: true这个字段设置为true。

如果在授予访问权限之前就先更新了数据库记录，而后续的GitHub操作又失败了，那么数据库中就会显示访问权限已经被授予，但实际上并没有。

步骤8：发送仓库访问权限确认邮件

await step.run("send-repo-access-email", async () => {
  await sendEmail({
    to: user.email,
    subject: `您的仓库访问权限已准备就绪！`,
    template: createElement(RepoAccessGrantedEmail, {
      repoUrl: "https://github.com/your-org/your-repo",
    }),
  });
});

这封邮件只有在GitHub邀请被确认（步骤5）且数据库记录被更新（步骤7）之后才会发送。这样的顺序安排非常重要，因为如果在邀请尚未发送的情况下就通知客户“访问权限已准备就绪”，那是不对的。

步骤9：安排后续操作流程

await step.run("schedule-follow-up", async () => {
  const purchaseRecord = await db
    .select({ id: purchases.id })
    .from(purchases)
    .where(eq(purchases.stripeCheckoutSessionId, sessionId))
    .limit(1);

  if (purchaseRecord[0]) {
    await inngest.send({
      name: "purchase/follow-up.scheduled",
      data: {
        userId,
        purchaseId: purchaseRecord[0].id,
        tier,
      },
    });
  }
});

最后一步会触发一个独立的 Inngest 函数，该函数负责发送后续邮件（第7天发送入职指南邮件，第14天发送反馈请求邮件，第30天发送推荐信请求邮件）。这是一个基于事件驱动的流程：一个函数完成执行后会触发另一个函数。

后续处理函数会使用 step.sleep() 来控制发送邮件的间隔时间：

export const handlePurchaseFollowUp = inngest.createFunction(
  {
    id: "purchase-follow-up",
    triggers: [{ event: "purchase/follow-up.scheduled" }],
    cancelOn: [
      {
        event: "purchase/follow-up.cancelled",
        match: "data.purchaseId",
      },
    ],
  },
  async ({ event, step }) => {
    const { userId, purchaseId } = event.data;

    await step.sleep("wait-7-days", "7d");

    await step.run("send-day-7-email", async () => {
      // 检查用户是否符合接收邮件的条件（用户存在、未取消订阅、未收到退款）
      // 发送入职指南邮件
    });

    await step.sleep("wait-14-days", "7d");

    await step.run("send-day-14-email", async () => {
      // 发送反馈请求邮件
    });

    await step.sleep("wait-30-days", "16d");

    await step.run("send-day-30-email", async () => {
      // 发送推荐信请求邮件
    });
  }
);

请注意 cancelOn 这个选项。如果用户的购买订单被退款，系统可以发送 purchase/follow-up.cancelled 事件，这样整个后续处理流程就会停止。这样一来，那些要求退款的用户就不会收到任何多余的邮件。

为什么每个步骤都必须是独立的

规则很简单：任何需要调用外部服务或可能会独立出现故障的操作，都应该被单独列为一个步骤。

数据库查询属于一个步骤，因为数据库有时可能会暂时无法访问；发送邮件也是一个步骤，因为邮件服务商可能会返回 500 错误代码；调用 GitHub API 也同样属于一个步骤，因为这种请求可能会受到速率限制。

如果两个操作总是同时成功或同时失败（因为它们共同依赖于同一个外部服务），那么可以将它们放在同一个步骤中。但如果有疑问的话，最好还是将它们分开处理。这样做带来的开销微乎其微，而可靠性却会显著提高。

如何使用相同的流程来处理退款操作

退款的整个处理流程也遵循完全相同的步骤结构。这个函数与 handlePurchaseCompleted 位于同一个文件中，因此它们共享相同的导入依赖项（还包括来自 @/lib/github 的 removeCollaborator 函数以及专门用于处理退款的邮件模板）。以下是 handleRefund 函数的代码实现：

export const handleRefund = inngest.createFunction(
  { id: "refund-processed", triggers: [{ event: "stripe/charge.refunded" }] },
  async ({ event, step }) => {
    const {
      chargeId,
      paymentIntentId,
      amountRefunded,
      originalAmount,
      currency,
    } = event.data;

    const isFullRefund = amountRefunded >= originalAmount;

    // 第一步：查找对应的购买记录和用户信息
    const { user, purchase } = await step.run(
      "lookup-purchase-by-payment-intent",
      async () => {
        const purchaseResult = await db
          .select({
            id: purchases.id,
            userId: purchases.userId,
            stripePaymentIntentId: purchases.stripePaymentIntentId,
            githubAccessGranted: purchases.githubAccessGranted,
          })
          .from(purchases)
          .where(eq(purchases.stripePaymentIntentId, paymentIntentId))
          .limit(1);

        const foundPurchase = purchaseResult[0];
        if (!foundPurchase) {
          return { user: null, purchase: null };
        }

        const userResult = await db
          .select({
            id: users.id,
            email: users.email,
            name: users.name,
            githubUsername: users.githubUsername,
          })
          .from(users)
          .where(eq(users.id, foundPurchase.userId))
          .limit(1);

        return { user: userResult[0] ?? null, purchase: foundPurchase };
      }
    );

    if (!purchase || !user) {
      return { success: false, reason: "未找到对应的购买记录或用户信息" };
    }

    let accessRevoked = false;

    // 第二步：如果退款金额为全额退款，那么撤销用户的GitHub访问权限
    if (isFullRefund && user.githubUsername && purchase.githubAccessGranted) {
      const revokeResult = await step.run(
        "revoke-github-access",
        async () => {
          return removeCollaborator(user.githubUsername!);
        }
      );
      accessRevoked = revokeResult.success;
    }

    // 第三步：更新购买记录的状态
    await step.run("update-purchase-status", async () => {
      if (isFullRefund) {
        await db
          .update(purchases)
          .set({
            status: "refunded",
            githubAccessGranted: false,
           .updated: new Date(),
          })
          .where(eq(purchases.id, purchase.id));
      } else {
        await db
          .update(purchases)
          .set({
            status: "partially_refunded",
            updated: new Date(),
          })
          .where(eq(purchases.id, purchase.id));
      }
    });

    // 第四步：在分析系统中记录退款操作
    await step.run("track-refund-event", async () => {
      await trackServerEvent(user.id, "refund_processed", {
        charge_id: chargeId,
        amount_cents: amountRefunded,
        original_amount_cents: originalAmount,
        currency,
        is_full_refund: isFullRefund,
        github_access_revoked: accessRevoked,
      });
    });

    // 第五步：通知客户退款结果
    await step.run("send-customer-notification", async () => {
      if (isFullRefund) {
        await sendEmail({
          to: user.email,
          subject: "您的退款已处理完成",
          template: createElement(AccessRevokedEmail, {
            customerEmail: user.email,
            refundAmount: amountRefunded,
            currency,
          }),
        });
      } else {
        await sendEmail(
          to: user.email,
          subject: "您的部分退款已处理完成",
          template: createElement(PartialRefundEmail, {
            customerEmail: user.email,
            refundAmount: amountRefunded,
            originalAmount,
            currency,
          }),
        );
      }
    });

    // 第六步：通知管理员退款结果
    await step.run("send-admin-notification", async () => {
      const adminEmail = process.env ADMIN_EMAIL;
      if (!adminEmail) return;

      await sendEmail(
        to: adminEmail,
        subject: `\({isFullRefund ? "全额退款" : "部分退款"}：\){user.email}`,
        template: createElement(AdminRefundNotificationEmail, {
          customerEmail: user.email,
          customerName: user.name,
          githubUsername: user.githubUsername,
          refundAmount: amountRefunded,
          originalAmount,
          currency,
          stripeChargeId: chargeId,
          accessRevoked,
          isPartialRefund: !isFullRefund,
        }),
      );
    });

    return { success: true, accessRevoked, isFullRefund, userId: user.id };
  }
);

在退款流程中，有三点值得特别注意。

1. 部分退款与全额退款的区别：该系统通过简单的判断来区分这两种情况：amountRefunded >= originalAmount。如果是部分退款，客户仍然可以继续使用相关服务，但购买状态会变为partially_refunded；而如果是全额退款，用户的GitHub访问权限会被取消，状态会变为refunded。

   这一机制对于维护数据库的准确性至关重要。后端系统（如数据看板、分析工具或支持界面）都需要获取准确的状态信息。

2. 条件性步骤执行：“取消GitHub访问权限”这一操作只有在满足三个条件时才会执行：必须是全额退款、用户拥有GitHub账户，并且之前确实被授予了访问权限。inngest通过跳过那些不必要的步骤，使这一流程更加清晰易懂。

   相比在单一处理函数中使用复杂的if-else结构，这种设计显然更易于阅读。

3. 为客户和管理员分别发送通知：如果退款是全额的还是部分的，系统会向客户发送不同的邮件。而管理员总会收到一份包含收费ID、客户GitHub用户名以及访问权限是否被取消等详细信息的通知。

之所以要分开这些步骤，是因为管理员通知失败不应影响客户通知的发送。客户的电子邮件通知具有更高的优先级。

如何恢复被放弃的购物车订单

在恢复被放弃的购物车订单时，step.sleep()方法发挥了重要作用。当Stripe的购物车会话过期后，系统需要发送一封提醒邮件，但此时不宜立即执行这一操作。

最好等待大约一小时，给客户足够的时间自行完成交易。

export const handleCheckoutExpired = inngest.createFunction(
  {
    id: "checkout-expired",
    triggers: [{ event: "stripe/checkout.session.expired" }],
  },
  async ({ event, step }) => {
    const { customerEmail, sessionId } = event.data;

    if (!customerEmail) {
      return { success: false, reason: "no_email" };
    }

    // 等待1小时后再发送提醒邮件
    await step.sleep("wait-before-recovery-email", "1h");

    // 发送恢复购物车订单的邮件
    await step.run("send-abandoned-cart-email", async () => {
      const checkoutUrl = `https://yoursite.com/pricing`;

      await sendEmail({
        to: customerEmail,
        subject: "您的购物车订单正在等待处理",
        template: createElement(AbandonedCartEmail, {
          customerEmail,
          checkoutUrl,
        }),
      });
    });

    // 记录这一操作
    await step.run("track-abandoned-cart", async () => {
      await trackServerEvent("anonymous", "abandoned_cart_email_sent", {
        customer_email: customerEmail,
        session_id: sessionId,
      });
    });

    return { success: true, customerEmail };
  }
);

step.sleep("wait-before-recovery-email", "1h")这一行代码是关键所在。它会让函数暂停运行一小时，而不会消耗任何计算资源。

Inngest会内部处理调度工作。一小时后，函数会重新开始执行并发送邮件。

如果没有这种可靠的执行机制，你就需要使用cron作业来查询数据库中过期的会话信息，或者利用Redis建立延迟任务队列，又或者是使用setTimeout函数，但这样的方法在服务器重启后就会失效。step.sleep()这种方式更为简单、易读，也更加可靠。

此外，该函数的顶部还设置了一个检测机制：如果Stripe没有记录该会话的顾客邮箱地址（即顾客在输入邮箱之前就完成了结账流程），函数会立即结束执行。如果没有可发送邮件的地址，安排恢复邮件的任务也就毫无意义了。

这种设计模式也可以应用于更复杂的恢复流程。例如，你可以再添加一个step.sleep()语句，如果三天后顾客仍未完成购买操作，就再发送一封跟进邮件；你还可以通过在step.run()中查询数据库来确认顾客是否已经完成了购买，如果是的话，就可以跳过发送邮件的步骤。

每增加一个处理步骤，就意味着需要多调用一次step.run()或step.sleep()。这样的函数代码读起来就像是在描述你的业务逻辑，而不是杂乱无章的cron作业和数据库配置指令。

如何在本机测试Webhook处理程序

对于Stripe提供的Webhook服务来说，本机测试确实是一个比较麻烦的问题。你需要让Stripe将事件发送到你的本地机器上，同时还需要确保你的后台作业系统能够正常运行以处理这些事件。以下是具体的设置步骤。

如何在本机转发Stripe事件

请安装Stripe CLI，然后将Webhook事件转发到你的本地服务器上：

stripe listen --forward-to localhost:3000/api/payments/webhook

CLI会输出一个用于签名Webhook请求的密钥（以whsec_开头）。请将这个密钥设置为STRIPE_WEBHOOK_SECRET环境变量，以便在本地开发环境中使用。

你也可以直接触发测试事件：

stripe trigger checkout.session_completed
stripe trigger charge/refunded
stripe trigger checkout.session.expired

如何运行Inngest开发服务器

Inngest提供了一个本地开发服务器，它可以实时显示每个函数的执行情况、每一步的具体操作以及所有的重试尝试：

npx inngest-cli@latest dev -u http://localhost:3000/api/inngest

-u参数用于告知Inngest开发服务器你的应用程序运行在哪个地址上，这样它才能正确地找到并执行相应的函数。你可以在浏览器中访问http://localhost:8288来查看Inngest的控制面板。

如何观察函数的执行过程

Inngest开发控制面板真正体现了这种可靠的执行模式的优势。当你触发一个Stripe事件时，你可以看到以下内容：

1. 该事件会出现在“事件”选项卡中。

2. 相关函数会在“运行记录”选项卡中被触发并执行。

3. 每个执行步骤都会被逐一显示，包括其输入数据、输出结果以及执行耗时。

4. 如果某个步骤失败了，你会看到错误信息以及系统尝试重试的次数。

这种透明度是内嵌式Webhook处理方式所无法提供的。当有客户反馈“我已经付款了，但仍然没有收到相应服务”时，你可以通过Inngest开发控制面板查看具体是哪个步骤失败了，以及失败的原因。在生产环境中，这样的可观测性至关重要。

如何模拟故障

为了测试系统的重试机制，你可以故意让某个步骤失败。例如，在“add-github-collaborator”这个步骤中人为地抛出一个错误：

const collaboratorResult = await step.run(
  "add-github-collaborator",
  async () => {
    throw new Error("模拟的GitHub API故障");
  }
);

在Inngest开发控制面板中，你会看到以下情况：

• 步骤1到步骤4都成功执行了，它们的结果也会被缓存下来。

• 步骤5失败了，系统会根据重试策略再次尝试执行它。

• 直到步骤5成功执行后，步骤6到步骤9才会继续被执行。

如果移除了之前抛出的错误，那么在下一次重试时，步骤5就会成功执行。此时步骤6到步骤9会按顺序继续执行，而步骤1到步骤4则不会被重新运行。这就是这种机制的实际运作效果。

结论

实现可靠的Stripe Webhook处理机制，关键在于遵循一个原则：**将数据接收与处理过程分开**。

你的Webhook端点只需要负责验证Stripe发送的签名信息，并将相关事件信息发送给后台作业系统即可。具体的处理工作则由那些具备持久性执行能力的函数来完成——每个执行步骤都会被单独记录下来，一旦失败就会自动重试。

这种机制能为你带来以下好处：

• **避免重复操作**：已经成功执行的步骤不会被重新运行。

• **确保状态的一致性**：如果某个步骤失败了，之前的步骤结果仍然会保留下来，失败步骤会独立地被重试。

• **实现全面的可观测性**：你可以清楚地了解每次函数执行过程中到底是哪个步骤出了问题，以及出错的原因。

• **具备延迟执行功能**：通过`step.sleep()`方法，可以无需使用cron作业来处理恢复邮件或后续操作。

• **支持灵活的工作流程组合**：一个函数可以通过事件触发另一个函数的执行，从而形成一系列连续的操作流程。例如，在用户完成购买后，系统会自动启动为期30天的后续服务流程。

这种处理模式并不局限于Stripe。任何需要多步骤处理的Webhook场景都能从这种持久性执行机制中受益——无论是用于触发CI管道的GitHub Webhook，还是用于跟踪邮件送达情况的Resend Webhook，甚至是用于在不同服务之间同步数据的日历Webhook，都可以从中获得好处。

原则是一样的：进行验证、将相关任务加入队列，然后持久地执行这些处理流程。

我在Eden Stack项目中实际应用了这种模式。在该系统中，购买流程涵盖了从支付确认到授予GitHub仓库访问权限，以及发送多轮电子邮件通知等所有环节。这套由9个步骤组成的购买处理流程从未出现过任何步骤遗漏或邮件重复发送的情况。

如果你正在使用Stripe开发SaaS产品，建议先从这篇文章中介绍的Webhook端点模式开始入手。保持端点的简洁性，将复杂的处理逻辑分步进行持久化执行。这样，当有客户反馈“我已经付款了，但什么都没有发生”时，你就不会在凌晨3点还要去调试系统了。

如果你希望获得一套预先构建好的Stripe Webhook集成方案，该方案应包含购买流程、退款处理机制以及后续邮件发送功能，并且能够直接投入使用，Eden Stack正好满足了这些需求。它不仅包含了这篇文章中介绍的所有内容，还提供了30多种经过生产环境测试的实用方案。

Magnus Rodseth专注于开发基于人工智能的应用程序，他是Eden Stack的创建者。Eden Stack是一套专为生产环境设计的首选工具包，其中包含了30多种用于开发基于人工智能的SaaS产品的实用方案。