Cloudflare Agents 从入门到精通
附录

§25 Webhook 与推送通知:接入真实世界事件

25.1 Webhook:让外部系统打 Agent

GitHub 推送、Stripe 支付、表单提交——都能用 Webhook 打到 Agent。

export default {
  async fetch(request: Request, env: Env) {
    // 用 HMAC-SHA256 校验签名,防伪造
    const valid = verifySignature(request, env.WEBHOOK_SECRET);
    if (!valid) return new Response("bad signature", { status: 401 });

    const payload = await request.json();
    const agent = await getAgentByName(env.MyAgent, payload.userId);
    await agent.handleEvent(payload); // 转给 Agent 处理
    return new Response("ok"); // 快速响应,重活在 Agent
  }
};
注意
Webhook 端点要"快进快出"。校验完立刻返回 200,重活交给 Agent 异步跑。外部系统超时重试会让你重复处理。

25.2 推送通知:客户端关了也能达

用户关了页面?用 Web Push(VAPID)把消息推到浏览器。Agent 配合 service worker 订阅,定时或事件触发时推送。

// 订阅 + 定时提醒的 Agent 内逻辑
await this.schedule("0 9 * * *", "sendPush", { title: "早报", body: "点开看今日摘要" });
维度 WebSocket Web Push 标叔的结论
客户端在线 实时双向 不需要在线 互补
离线可达 推送补离线
典型 聊天 提醒/告警 两个都配
核心建议
实时交互用 WebSocket,离线提醒用 Push。一个 Agent 两种通道都接,体验才完整。

Webhook 讲完。下一章讲语音——让 Agent 开口说话。