用 Claude Code 构建 SaaS 集成：API Key、OAuth、Webhook 与审计日志

用 Claude Code 构建 SaaS 集成时，第一个问题不应该是“调用哪个 endpoint”。更重要的问题是：如何安全授权，失败后如何重试而不产生重复副作用，以及事后如何说明是谁做了什么。如果跳过这一层，即使只是一个 Slack 通知，也可能变成安全、计费或运维问题。

本文把 API Key、OAuth、Webhook、rate limit、retry、idempotency、audit log、secret 和 test environment 整理成适合 Claude Code 的实践流程。Webhook 是 SaaS 主动发送到你服务器的事件。Idempotency 是“同一个操作重复执行也不会产生重复结果”的性质。Audit log 是事后解释自动化行为的记录。

示例基于 Node.js 20 或更高版本，可以直接复制到 scripts/ 目录中使用。

集成架构

不要让 Claude Code 成为唯一保存集成状态的地方。Claude Code 适合规划、生成代码和执行命令；token、retry 状态和 audit history 应该放在 connector 代码里。

flowchart LR
  A[Claude Code] --> B[CLI or MCP connector]
  B --> C[Auth and secret store]
  B --> D[Retry and rate-limit wrapper]
  D --> E[SaaS API]
  E --> F[Webhook receiver]
  F --> G[Queue]
  G --> H[Worker]
  H --> I[Audit log]

最小可用形态是 CLI wrapper，例如让 Claude Code 调用 node scripts/slack-notify.mjs。如果 workflow 经常使用，就可以升级成 MCP server，复用输入 schema、权限和错误处理。Webhook receiver 的成本更高，但当 Stripe、GitHub、Slack 或其他 SaaS 作为流程触发方时，它是必要的。

四个具体场景

第一个场景是 release 运营。Claude Code 读取 GitHub 中尚未发布的 commits，生成 release notes，并把简短摘要发到 Slack。Slack Incoming Webhooks 设置很快，但不适合删除消息或复杂 chat flow；需要更强控制时应使用 Slack Web API。

第二个场景是 billing automation。Stripe webhook 接收 checkout.session.completed，把客户写入内部工具，并把失败任务放进 retry queue。这里必须有 signature verification、idempotency key，以及 test mode 和 live mode 的严格分离。

第三个场景是 support triage。Google Workspace OAuth 让 backend 读取 support CSV，Claude Code 对行进行分类，然后创建 GitHub issues 交给 engineering 跟进。由于流程接触用户数据，窄范围 read-only OAuth scope 比共享 API key 更安全。

第四个场景是 audit dashboard。Claude Code 触发的每个 SaaS action 都写成 NDJSON，让团队能看到 actor、provider、action、target 和 idempotency key。即使还没有正式审计平台，这也很有价值。

选择 API Key、OAuth、Webhook 或 Connector

方式	简单解释	适合场景	注意事项
API key	服务端共享凭证	Stripe 服务端调用、内部 Slack 通知	放在环境变量或 secret manager，不要写进源码
OAuth	用户或 workspace 授权访问	Google Drive、GitHub Apps、按用户执行的操作	refresh token 和 scope 要认真设计
Webhook	SaaS 把事件发送到你的 endpoint	Stripe 支付、GitHub issue、Slack event	验证签名，处理重复投递，不假设顺序
CLI/MCP connector	Claude Code 可以调用的稳定工具层	runbook、内部运维、跨 SaaS workflow	validation 和 logging 放在 connector 中

Google OAuth 2.0 文档解释了 access token 和 refresh token 的流程。GitHub 与 Slack 集成也需要带 actor 的日志，因为排查权限问题时，“bot 做的”并不是足够的答案。

环境变量检查清单

先创建 .env.example，只共享变量名。真实值不要进入 Git。

# .env.example
INTEGRATION_ENV=sandbox
SAAS_API_TOKEN=
SLACK_WEBHOOK_URL=
GITHUB_WEBHOOK_SECRET=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
STRIPE_SECRET_KEY=sk_test_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
AUDIT_LOG_PATH=logs/saas-audit.ndjson

# .gitignore
.env
.env.*
!.env.example
logs/

让 Claude Code 执行集成前，检查这些事项：

• live key 和 test key 位于不同 environment。
• 不把 secret 粘贴到 Claude Code prompt。
• error message 不打印 Authorization header 或 webhook secret。
• OAuth scope 从 read-only 开始，只在必要时扩大。
• CI 值作为 secret 注册，而不是普通 repository variable。
• 记录 key rotation 的日期和负责人。

Retry 与 Rate Limit Wrapper

Rate limit 是 provider 允许的最大请求速度。GitHub REST API 有 primary limit 和 secondary limit；触发限制时需要遵守 response header。Slack 会返回 429 Too Many Requests 和 Retry-After。这些行为应该写在代码里，而不是只靠 prompt 指令。

// scripts/saas-request.mjs
import crypto from "node:crypto";
import { pathToFileURL } from "node:url";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

export async function saasRequest(url, options = {}) {
  const {
    method = "GET",
    token = process.env.SAAS_API_TOKEN,
    body,
    idempotencyKey = method === "POST" ? crypto.randomUUID() : undefined,
    maxRetries = 4,
    headers = {},
  } = options;

  for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
    const res = await fetch(url, {
      method,
      headers: {
        Accept: "application/json",
        ...(body ? { "Content-Type": "application/json" } : {}),
        ...(token ? { Authorization: `Bearer ${token}` } : {}),
        ...(idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {}),
        ...headers,
      },
      body: body ? JSON.stringify(body) : undefined,
    });

    if (res.ok) return res;

    const retryAfter = Number(res.headers.get("retry-after"));
    const shouldRetry = [408, 409, 425, 429, 500, 502, 503, 504].includes(res.status);

    if (!shouldRetry || attempt === maxRetries) {
      const text = await res.text();
      throw new Error(`SaaS request failed: ${res.status} ${text.slice(0, 200)}`);
    }

    const backoffMs = Number.isFinite(retryAfter)
      ? retryAfter * 1000
      : Math.min(30000, 500 * 2 ** attempt);

    await sleep(backoffMs);
  }

  throw new Error("unreachable");
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const url = process.argv[2];
  if (!url) throw new Error("Usage: node scripts/saas-request.mjs <url>");
  const res = await saasRequest(url);
  console.log(await res.text());
}

Stripe 等支持 idempotency key 的 API 可以安全重试同一个 POST。你自己的 worker 也应使用类似 provider + event_id + action 的 key，已经处理过就跳过。

Webhook 验证流程

Webhook 是公开 HTTP 入口。没有 signature verification，任何人都可能发送伪造事件。GitHub 使用 X-Hub-Signature-256，Stripe 使用 Stripe-Signature。关键规则是：在解析 JSON 之前验证 raw body。

1. 读取 raw body。
2. 读取 signature header。
3. 用 shared secret 计算 HMAC。
4. 使用 timing-safe comparison 比较。
5. 把 delivery id 保存为 idempotency key。
6. 快速返回 202，重任务放入 queue 处理。

// scripts/verify-github-webhook.mjs
import crypto from "node:crypto";
import http from "node:http";

const secret = process.env.GITHUB_WEBHOOK_SECRET;
if (!secret) throw new Error("Set GITHUB_WEBHOOK_SECRET");

function verifyGitHubSignature(rawBody, signatureHeader) {
  const received = Array.isArray(signatureHeader)
    ? signatureHeader[0]
    : signatureHeader ?? "";
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const receivedBytes = Buffer.from(received);
  const expectedBytes = Buffer.from(expected);

  return (
    receivedBytes.length === expectedBytes.length &&
    crypto.timingSafeEqual(receivedBytes, expectedBytes)
  );
}

http
  .createServer(async (req, res) => {
    const chunks = [];
    for await (const chunk of req) chunks.push(chunk);
    const rawBody = Buffer.concat(chunks);

    if (!verifyGitHubSignature(rawBody, req.headers["x-hub-signature-256"])) {
      res.writeHead(401);
      res.end("invalid signature");
      return;
    }

    const event = req.headers["x-github-event"];
    const delivery = req.headers["x-github-delivery"];
    console.log(JSON.stringify({ event, delivery, receivedAt: new Date().toISOString() }));

    res.writeHead(202, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ ok: true }));
  })
  .listen(3000, () => console.log("Listening on http://localhost:3000"));

Stripe 在生产中建议使用官方 SDK 的 constructEvent()。test webhook secret 和 live webhook secret 不同，因此 STRIPE_WEBHOOK_SECRET 要按环境管理。

审计日志

Audit log 是事后解释自动化动作的记录。Claude Code 的聊天历史不够，需要保存 timestamp、actor、provider、action、target、idempotency key 和 status。

{
  "ts": "2026-06-03T09:15:00.000Z",
  "actor": "claude-code",
  "provider": "github",
  "action": "create_issue",
  "target": "owner/repo#123",
  "idempotencyKey": "github:issue:customer-42:2026-06-03",
  "status": "succeeded"
}

// scripts/audit-log.mjs
import { appendFile, mkdir } from "node:fs/promises";
import { dirname } from "node:path";

export async function writeAudit(event) {
  const record = {
    ts: new Date().toISOString(),
    actor: event.actor ?? "claude-code",
    provider: event.provider,
    action: event.action,
    target: event.target,
    idempotencyKey: event.idempotencyKey,
    status: event.status ?? "started",
  };
  const file = process.env.AUDIT_LOG_PATH ?? "logs/saas-audit.ndjson";
  await mkdir(dirname(file), { recursive: true });
  await appendFile(file, `${JSON.stringify(record)}\n`, "utf8");
}

if (process.argv[1]?.endsWith("audit-log.mjs")) {
  await writeAudit({
    provider: "slack",
    action: "post_message",
    target: "#release",
    idempotencyKey: "demo-2026-06-03",
    status: "succeeded",
  });
}

第一版使用 NDJSON 就足够。之后可以导入 BigQuery、DuckDB 或电子表格。

常见陷阱

第一个陷阱是尝试把 webhook 直接发送到 localhost。GitHub troubleshooting 文档说明 webhook URL 必须公网可访问。local test 可以使用 forwarding service，production 使用 HTTPS endpoint。

第二个陷阱是相信 webhook 顺序。Provider 可能延迟或乱序发送 event。不要依赖到达顺序，而要使用 event timestamp、delivery id 和 resource 当前状态。

第三个问题是 retry 导致重复工作。payment、issue、Slack post 和 email 都会被用户看到。给 POST 添加 idempotency key，并在 worker 中保存已经处理过的 delivery id。

第四个陷阱是 OAuth scope 过大。从 read-only、单个 folder 或 workspace、短生命周期 token 开始。只有在风险清楚后再扩大 scope。

第五个陷阱是把 secret 粘贴进 Claude Code。让 Claude Code 使用环境变量名；真实值放在 secret manager、CI secret 或本地 .env。

什么时候抽象 Connector

第一个 script 可以直接、简单。只要 authorization、pagination、rate limiting、audit logging、error formatting 在三个 workflow 中重复出现，就该创建 connector。

抽象名称要使用业务语言：sendMessage()、createTicket()、recordPaymentEvent()、writeAudit()。薄薄的 callSlackApi() wrapper 不如直接表达 workflow 结果的函数适合 Claude Code。

相关实现可以结合 Claude Code API Design Assistant 和 Claude Code API Testing。在生产访问前，建议先阅读 Claude Code Security Best Practices 做风险检查。

官方参考

• Stripe: webhook signature verification
• Stripe: idempotent requests
• Slack: Incoming Webhooks
• Slack: Web API rate limits
• GitHub: validating webhook deliveries
• GitHub: REST API rate limits
• Google: OAuth 2.0 for Google APIs

如果要把 Claude Code 集成放进团队 workflow，请在第一次事故前准备可复用模板。实践 checklist 在 /products/，团队导入培训在 /training/。

实际测试后可以看到，从第一天就包含 signature verification、idempotency、audit log 和独立 test environment 的集成更容易扩展。即使只是一个小的 Slack 通知，只要失败可以追踪并有意识地 replay，可靠性也会明显提高。