AnyHook 文档

AnyHook 不需要 SDK，也不需要安装任何包：你只需在发送方的控制台里替换 Webhook URL，你的处理程序收到的还是同样的请求。有一点需要提前考虑：重试和重放带的是发送方的原始时间戳，所以对于签名会过期的发送方（Stripe、Slack，以及 /providers 上标有时间容差的其他平台），要验证 AnyHook-Signature 才能接受这些请求。

最快的方式（无需账号）：运行 curl -X POST https://anyhook.net/api/v1/quickstart，立即拿到一个可用的接收 URL 和 API 密钥，适合 AI 智能体和快速测试。这个端点 7 天后过期，除非通过返回的 claim_url 认领。把发送方指向返回的 inbound_url，再用 GET /api/v1/events 和 GET /api/v1/events/{id} 读取事件；响应里的 next_steps 列出了每一条命令。

1. 1
   创建账号

   打开 anyhook.net/sign-up，创建一个免费账号。无需绑定信用卡。
2. 2
   创建一个 App

   一个 App 代表一个 Webhook 来源。新账号会直接打开创建表单：给它起个名字（例如“Stripe Production”），还可以选填你自己的服务器 URL，AnyHook 收到每个事件后会转发到这里。留空的话，这个 App 只记录所有事件，不转发。转发目标可以随时添加，Free 套餐每个 App 最多 3 个。
3. 3
   把发送方指向 AnyHook

   App 页面会显示你的接收 URL，以及常见发送方在哪里填写它（例如 Stripe → Developers → Webhooks）。把它粘贴到那里，替换原来的 Webhook URL：

   https://in.anyhook.net/{user-slug}/{app-slug}

   这个页面会实时监听：第一个请求几秒内就会出现在页面上。还没有可以发送请求的来源？在同一页面上点击 Send a test event。

每个 App 都有一个唯一的接收 URL：

https://in.anyhook.net/{user-slug}/{app-slug}

• user-slug：你的账号标识，可以在控制台的设置中看到。
• app-slug：每个 App 唯一，根据 App 名称自动生成，可以修改。

接收端点接受任何 POST 请求，也会应答配置时的验证握手：带有 hub.mode=subscribe 的 GET 请求（Meta 的 hub.challenge 校验）会被自动回显，即使 App 还没配置好。其他方法一律返回 405。网页和普通的 HTML 表单也可以向它提交（见代码处理程序）。事件一旦持久化入队，AnyHook 就会返回 HTTP 200，约需 1 秒，不受你的转发目标端点速度的影响，所以发送方从不需要等它。

AnyHook 根据收到的请求头自动识别发送方，并在边缘节点验证请求体签名。要启用验证，创建 App 时选择你的 Webhook 平台，然后粘贴该平台的 Webhook 签名密钥（例如 Stripe 的 whsec_...）。

未通过验证的请求会在边缘节点被拒收，永远不会到达你的端点。App 页面会统计它们的数量，每天的前 5 个会以 rejected 状态保存在事件日志里，请求头和请求体都在，方便你查看原因。

AnyHook 采用基于队列的异步架构，把 Webhook 发送方和你的后端解耦：

1. 边缘接收：Cloudflare Workers 接收 POST 请求，验证签名，在事件持久化保存后返回 200，整个过程约 1 秒。
2. 入队：事件被发布到持久化消息队列（Upstash QStash）。此时发送方的 HTTP 连接已经关闭。
3. 转发：QStash 把事件投递给 AnyHook 的转发器，转发器再把原始请求体 POST 到你的转发目标端点。
4. 记录：每一步都会记录下来，包括收到的请求头/请求体、投递状态、你的端点返回的状态码和响应体，以及延迟。

我们把约定直接写清楚，因为一个对自身保证含糊其辞的转发服务，会把这份含糊推给你的代码：

1. 至少一次，而不是精确一次。重试本身就是这个产品，而响应丢失后的重试与一次新的投递无法区分。你偶尔会收到同一个事件两次；没有哪个转发服务能做出相反的承诺，那些这样承诺的，说的只是一切顺利时的情况。你的处理程序必须幂等，我们在 X-AnyHook-Delivery 中转发的事件 ID 就是去重用的键。
2. 不保证顺序。由于重试和并发投递，较晚的事件可能比仍在重试中的较早事件先到。大多数发送方在我们的上游也不承诺顺序。按请求体里的字段排序（版本号、updated_at），永远不要按到达时间排序。
3. 不要按签名去重。AnyHook-Signature 在每次尝试时都会用新的时间戳重新签名，这是有意为之，这样重试永远不会超出你的时间容差。同一个事件的两次投递带着不同的签名；保持不变的是事件 id。
4. 已接收即已持久化。边缘节点只在事件持久化之后才返回 200；队列之后还有两个备用存储，都失败了才会改为返回 503。接收 URL 返回 503 意味着什么都没有保存，这时发送方自己的重试就是安全网，这也正是我们返回 503 而不是假装成功的原因。

当你的转发目标返回可重试错误或超时，AnyHook 会按指数退避自动重试：

哪些响应会触发重试？

并非所有错误都可以重试。AnyHook 会对你的端点的响应分类，避免把尝试次数或你的计算额度花在再试也解决不了的错误上：

每次尝试都会记录完整的响应体和状态码。不可重试的 4xx 失败和可重试的失败都会计入熔断器，任何类型的失败连续 20 次都会触发熔断器。

失败通知

AnyHook 在特定阈值发送邮件告警，而不是每个事件发一封，这样你的邮箱不会被告警淹没：

• 第 1 次失败：立即告警，附上状态码和转发目标。
• 连续第 5 次失败：升级告警，附上处理建议。
• 连续第 20 次失败：熔断器触发（见下文），发送熔断告警。

上面每个阈值各发一封邮件，之后熔断器的每一级（每次暂停和停用）各发一封，绝不会为每个事件发一封。任何一次投递成功都会重置计数。

如果 AnyHook 检测到同一个转发目标连续 20 次投递失败（包括不可重试的 4xx），熔断器就会触发，并开始逐级升级：

工作方式

• 照常接收。你的接收 URL 始终可用，来自 Stripe、GitHub 等平台的事件仍会被接收和保存。暂停的只是对你的转发目标的投递。
• 每次暂停结束后，AnyHook 会发起一次半开探测：用下一个事件测试你的转发目标。如果成功，熔断器闭合，一切重置。
• 任何一次成功都会重置一切：连续失败次数和触发次数都归零。
• 暂停期间收到的事件会以 circuit_open 状态保存，转发目标恢复后可以重放。
• 每升级一级，你都会收到一封邮件通知，包括转发目标 URL、失败次数和暂停时长。
• 如果转发目标已停用（第 5 次触发），你必须在控制台中手动重新启用它。

这种逐级升级的方式给你的服务器留出恢复时间，同时让你的计算额度免于被失效端点上的重试白白消耗。

到达你的接收 URL 的每个事件都会被记录，不管它的投递结果如何。日志从你把平台指向 AnyHook 时开始：在那之前失败的事件只存在于平台那边（Stripe 的情况见如何重放 Webhook）。每条日志包括：

• 完整的请求头和请求体（与从发送方收到的一致）
• 投递状态：queued → success / retrying / failed / rejected / circuit_open / quota_exceeded。rejected 表示 AnyHook 拒收了这个事件（签名验证失败，或转发目标 URL 被屏蔽）；它从未被尝试投递，也不能重放。
• 你的转发目标返回的 HTTP 状态码和响应体（每次尝试）
• 延迟（毫秒）
• 尝试次数和下次重试时间
• 该事件是否为重放（is_replay: true）

事件保留多久取决于套餐。Free：3 天，期间都可以重放，之后删除。Pro：1 年：前 30 天可以重放，之后转入只读的加密归档。Scale：7 年：前 90 天可以重放，之后转入只读的加密归档。Enterprise：灵活。

日志里的任何事件都可以在控制台中一键重放。重放会把保存的请求体逐字节发送到该事件原来的转发目标；如果你之后改过这个转发目标的 URL，就发送到新的 URL。

• 打开 Dashboard → Events
• 找到该事件，点击 Replay
• 系统会创建一个带 is_replay: true 的新事件，并关联到原始事件

AnyHook 开箱即支持本地开发，不需要特殊模式或 CLI。有两种做法：

1. 通过内网穿透实时转发

把 App 的转发目标设成指向你本机的内网穿透地址。任何内网穿透工具都可以：

# ngrok
ngrok http 3000
# → https://abc123.ngrok.io

# cloudflared
cloudflared tunnel --url http://localhost:3000

# localhost.run
ssh -R 80:localhost:3000 nokey@localhost.run

在控制台里把穿透地址填到 App 的转发目标中。AnyHook 会像对待其他端点一样把 Webhook 转发过去，重试、日志和签名请求头都完全一样。

2. 捕获事件并重放到 localhost

让真实的生产环境事件在 AnyHook 里积累，需要时把其中任何一个重放到你的本地环境。不用手动触发测试事件，用真实的请求体测试，次数只受每日重放上限限制。

• 把转发目标切换为你的穿透地址
• 打开 Dashboard → Events，在任意事件上点击 Replay
• 或者调用 API：POST /api/v1/events/{id}/replay
• 原始请求体会逐字节发送到你当前的转发目标

这在调试边界情况时特别有用：在生产日志里找到出问题的事件，在本地重放，反复修改，直到你的处理程序正确运行。

所有 Webhook 请求体数据在写入数据库之前，都会用 AES-256-GCM 进行静态加密。这包括收到的请求头、请求体，以及每个转发目标的签名密钥。

加密使用一个专用密钥（AES_SECRET_KEY），与数据库凭据分开存放。数据库泄露而加密密钥没有泄露时，攻击者只能拿到密文：没有明文的 Webhook 数据，没有签名密钥，也没有客户信息。

AnyHook 在 Cloudflare 边缘节点验证 Webhook 签名，在事件进入队列之前就完成验证。App 设置了签名密钥后，签名缺失或无效的请求会被拒收并返回 401，从不占用你的配额；没有密钥时，请求会不经验证就转发。

签名检测根据请求头自动进行。创建 App 并选择来源类型后，AnyHook 会保存签名密钥（静态加密），并对该平台使用正确的算法。

不在列表中的来源或自定义来源

如果你的 Webhook 来源不在支持列表里，创建 App 时选择 Generic。AnyHook 会：

• 接收每一个发来的 POST 并放入队列，不验证收到的签名。
• 把逐字节不变的请求体和平台的原始请求头转发到你的转发目标，每次尝试都附上新的 AnyHook-Signature。在我们的边缘节点之前添加的基础设施请求头（cf-* 之类）会被去掉。
• 附加一个 AnyHook-Signature 请求头，让你的端点仍然可以验证请求经过了 AnyHook。

Generic 类型的 App 不验证收到的签名，无论设置了什么密钥。AnyHook-Signature 证明的是请求经过了 AnyHook，而不是谁把它发给了 AnyHook；如果你需要后者，就保留你自己对发送方原始请求头的验证（这个请求头会原样转发）。如果发送方用 Standard Webhooks 签名（webhook-id、webhook-timestamp、webhook-signature，OpenAI 和 Replicate 就是这样），改选这个来源：它会在边缘节点验证。

每个转发目标有三项可选设置，Pro 及以上套餐都可以用。在 App → Destinations → Delivery controls 中设置，或者在转发目标对象上用 PATCH /api/v1/apps/{slug} 设置。Free 账号会保留付费期间设置的控制项，但不能修改。

{
  "destinations": [{
    "url": "https://api.example.com/hooks/stripe",
    "event_types": ["invoice.*", "checkout.session.completed"],
    "rate_limit": 20,
    "delay_seconds": 5
  }]
}

在 Pro 和 Scale 套餐上，App 可以对收到的每个事件运行你自己的代码：在沙箱里运行，不需要你自己的服务器。保存代码后，App 会多出一个运行这段代码的转发目标，所以重试、重放、熔断器和事件日志的工作方式与其他转发目标完全一样，每次运行的控制台输出和返回值就是那次投递的响应。在 App 的 Code 部分编写代码，或使用下面的接口。常见操作的模板在 /code-templates.md，从 Pipedream 迁移有专门的指南。

export default async function (event, { env, store }) {
  // event: { method, headers, body, raw_body, delivery_id, attempt }
  console.log(event.body);
}

• 事件。body 是解析后的 JSON、表单字段（urlencoded，或 multipart 表单中的文本字段）或原始文本，raw_body 是收到时的原始文本。method 始终是 POST；查询字符串、路径和调用方的 IP 都不会保留。delivery_id 是事件的 X-AnyHook-Delivery ID，attempt 从 1 开始计数，测试运行时为 0。
• 失败。抛出异常会让这次投递失败，之后按套餐的尝试次数重试（重试计划）。如果某个事件的运行已经成功，重试不会再运行它；但如果运行在某个调用已经完成之后才失败，重试会再运行一次，所以在 API 允许的地方，用 delivery_id 作为这类调用的幂等键。
• Pipedream 步骤。export default defineComponent({ async run({ steps, $ }) {} }) 也能运行：steps.trigger.event 就是上面的事件，$.export 和 $.flow.exit 都可用，每个 data_store prop 都是这个 App 的存储，app prop 的 $auth.field 读取密钥 APP_FIELD，其他 prop 读取以它命名的密钥（channelId 读取 CHANNEL_ID）。Pipedream 迁移指南列出了哪些不能沿用。
• npm 包。代码导入的包会在保存时安装，用 Pipedream 的方式锁定版本（import axios from "axios@1.7.9"），最多 20 个包。需要安装新包的保存可能要几分钟；安装失败则不会保存任何内容。
• 密钥。用 env.NAME 或 process.env.NAME 读取，最多 20 个，名称由字母、数字和下划线组成，不能以数字开头。PATH, HOME, NODE_OPTIONS, NODE_PATH, PWD 以及以 ANYHOOK_ 开头的名称归运行时所有，每个值最多 4,000 个字符。值永远不会离开服务器。
• 存储。store.get、set（{ ttl } 以秒为单位）、has、delete、keys、entries 和 clear 在事件之间保存状态，每个 App 一个存储：最多 1,000 个键，每个键最长 256 个字符，每个值序列化为 JSON 后最多 64,000 字节。导入时接受 {"entries": {key: value}}，会覆盖已存在的键，导入的键都没有 TTL。
• 定时任务。schedule 是五个 cron 字段，默认使用 UTC，除非加上 CRON_TZ=Area/City 前缀。每次触发都会向 App 自己的 URL 发送一个 anyhook.schedule 事件，所以它既计为一次运行，也计为一个事件，并且只在代码开启时触发。这个 App 的来源必须是 generic 或 auto，且不能设置签名密钥：给定时代码单独建一个 App。
• 邮件。每个 App 还可以在 {user-slug}.{app-slug}@anyhook.net 收邮件，邮件会变成一个 email.received 事件，请求体包含 from、to、subject、message_id、date、size，以及作为 raw 的 MIME 邮件原文。和定时任务一样，它需要一个来源为 generic 或 auto、没有签名密钥的 App；超过套餐请求体上限的邮件会被退回。
• 网页和表单。网页可以用 fetch() 请求接收 URL：边缘节点会应答 CORS 预检请求，每个响应都带有 Access-Control-Allow-Origin: *。普通的 HTML 表单需要 method="post"。在表单的 action 后加上 ?redirect=https://your-site.com/thanks，事件保存后，访客会被 303 重定向到那里，前提是这个地址和提交表单的页面在同一个站点上；否则访客会看到一个简短的“Received”页面。文本字段会出现在 event.body 中；上传的文件无法保留。
• 限制。代码最多 64,000 字节，每次运行在 Pro 套餐最长 105 秒，在 Scale 套餐最长 285 秒。每次运行保留控制台输出的最后 16,000 个字符。每月的运行次数见套餐对比表，每次运行都计数，包括重试、测试运行、重放和定时任务触发。没有超额计费：超出当月运行次数后，发往代码的投递会返回 429 并被暂存（circuit_open），不重试，等到下个月或升级套餐后即可重放。
• 测试与开关。POST .../code/test 用 App 最近保存的事件、你指定的 event_id 或你传入的 body 运行已保存的代码，并返回日志、返回值和耗时。它计为一次运行，不投递任何东西，但代码自己发出的请求确实会发出。只有在代码开启时，事件才会运行它。控制台保存新代码时默认关闭；而 PUT .../code 保存第一个版本时会直接开启，除非你传入 "enabled": false；之后的保存保持当前状态。如果另一个转发目标仍在处理同样的事件（比如迁移期间），用 "enabled": false 保存，移除那个转发目标之后再开启代码。两种更改都需要最多一分钟才能同步到所有边缘节点。

所有 API 请求都需要在 Authorization 请求头中携带 Bearer 令牌：

Authorization: Bearer ahk_live_xxxxxxxxxxxxxxxx

在 Dashboard → Settings → API Keys 中生成 API 密钥。密钥的作用范围是你的账号，可以是完全访问或只读访问（创建时选择），并且可以随时吊销。通过 MCP 登录（anyhook.net/mcp）连接的应用，可以用它的 OAuth 访问令牌调用同样的接口，权限以你批准的范围为限。

AnyHook 是一个位于 https://anyhook.net/mcp 的 MCP 服务器，智能体可以替你创建 App、读取事件日志、重放失败的事件，在 Pro 和 Scale 套餐上还能部署和测试 App 的代码（anyhook_code_deploy、anyhook_code_test、anyhook_code_get）。Claude Code、claude.ai、Codex和VS Code 只需这个 URL 和浏览器登录就能连接，不用复制密钥：各客户端的步骤。

Cursor、Windsurf 和 Claude Desktop 使用密钥连接。在 Dashboard → Settings → API Keys 下创建一个，页面会显示下面这段配置，你的密钥已经填好：

{
  "mcpServers": {
    "anyhook": {
      "command": "npx",
      "args": [
        "-y",
        "anyhook-mcp"
      ],
      "env": {
        "ANYHOOK_API_KEY": "ahk_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor：Settings → MCP → Add new MCP server，或 ~/.cursor/mcp.json。Windsurf：~/.codeium/windsurf/mcp_config.json。Claude Desktop：Settings → Developer → Edit Config。代码相关工具需要 anyhook-mcp 0.4.0 或更高版本（npx -y 会自动获取），或者使用 https://anyhook.net/mcp 上的服务器。

然后对它说：“为我的 Stripe Webhook 创建一个 AnyHook App，并把它的 URL 给我。”这些内容智能体都可以在 /llms.txt 中读到。

查看完整的价格详情 →