# @happyvertical/smrt-webhooks 中文文档

规范地址：https://npmcn.com/package/%40happyvertical/smrt-webhooks/

版本：0\.62\.1
npm 元数据更新时间：2026-11-17T07:55:43.094Z
中文译文更新时间：2026-11-17T10:33:39.240Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happyvertical/smrt-webhooks
原文对照：https://npmcn.com/package/%40happyvertical/smrt-webhooks/?lang=original
项目主页：https://github.com/happyvertical/smrt#readme
源码仓库：https://github.com/happyvertical/smrt

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：229 kB，46 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：5 个
- peer 依赖：svelte ^5\.57\.0
- 首次发布：2026-10-15T14:00:16.146Z
- 最新版本发布：2026-11-17T07:55:42.928Z
- 近 30 天下载量：13786（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：103（近 12 个月 103 个）

## 中文简介

外出网约车订阅、签名交付和耐久重试

## 安装

```sh
npm install @happyvertical/smrt-webhooks
```

也可以使用：`pnpm add @happyvertical/smrt-webhooks`、`yarn add @happyvertical/smrt-webhooks`、`bun add @happyvertical/smrt-webhooks`

## README

# 外出网点

`@happyvertical/smrt-webhooks` 提供租户范围创建、更新、删除和 从自定义事件到公共 HTTPS 端点, 带有 HMAC 签名, 持久任务 队列,重试/后退, 以及安全发送日志 .

## 服务器设置

将软件包模型和工作系统表格与正常应用程序相匹配 在开始工作之前,移民流动。 运行时代码从未创建应用程序 计划 仅在节点服务器中运行; 导入 UI `/svelte` 分别.

```ts
import {
  WebhookDispatcher, WebhookAdminService,
  registerWebhookRuntime, WebhookChangeFeed,
} from '@happyvertical/smrt-webhooks';
import { TaskRunner } from '@happyvertical/smrt-jobs';

const webhooks = new WebhookDispatcher({ db, runtime: 'application-webhooks' });
registerWebhookRuntime('application-webhooks', webhooks);
const events = new WebhookChangeFeed(webhooks, { orders: '@example/app:Order' });
// Poll from a host scheduler inside each authenticated tenant context.
await events.poll();
const admin = new WebhookAdminService(webhooks.store, async () =>
  currentUserHasPermission('webhooks:admin'));
const runner = new TaskRunner({ queues: ['webhooks'] });
await runner.initialize(db);
await runner.start();
```

在开始工作之前,在每一个工人过程中登记相同的运行时间名称. 跑者恢复了被捕获的租户背景;所有服务电话都要求 主机的认证 `withTenant` 上下文。 不从 客户提供租户身份证。 取消注册可选钩和呼叫 `unregisterWebhookRuntime()` 关闭。 服务器条目故意不保护浏览器安全.

生命周期订阅使用合格的模型名. 建议的持久道路是: `WebhookChangeFeed`: 将物理应用表映射到 每个租户的情况。 它读取了S-m-r-t承诺的更改种子(包括删除) 墓碑),仅公布身份 `{ id }` 有效载荷和进步持续 租户/运行时间光标只有在发包箱/工作持久后才能使用。 部分失败或 在光标前进重放稳定变化序列ID之前处理死亡, 与已经排好队的交货相矛盾 全球记录和其他 租户被排除在外。 共享的科技和创新表格必须映射到其基准模型:种子 不给儿童歧视者编码。 自定义绕过 s-m-r-t 持久性的 SQL 必须明确附加其域事件或核心更改输入.

比核心换料保留更频繁的投注. 凸起光标 `WebhookHistoryExpiredError` 停止而不是默默地放弃历史. 在操作员调和源状态并公布任何可收回的缺失后 活动,呼叫 `resumeAfterResync(error.resumeCursor)`. 失去的历史过渡 无法仅从当前状态快照重建; 保留域事件 如果需要这种保证的话,历史。 保持每次运行时间一个稳定的模型映射; 在光标被推进后添加表格不会回填旧事件.

`registerWebhookModelEvents` 是一种替代的低纬度钩,与 明确的模式允许列表。 也只公布身份 和钩子不是原子: 源执行和钩子等号之间的相撞可以 错过一个活动。 当这一差距是不可接受的时,采用持久的变革路径. 不为同一模型启用两条路径: 它们的事件ID代表不同的 出版物流。 两个路径都无法保证原子网络效应与源 写作。 Hooks 传播等效失败; 重新保存源对象不 重建缺失的历史创建/更新事件.

对于自定义事件,授权服务器上的数据投影 :

```ts
await webhooks.dispatch({
  id: durableDomainEventId, event: 'custom.paid', model: '@example/app:Invoice',
  occurredAt: new Date().toISOString(), data: { id: invoiceId },
});
```

空事件/模型过滤器指所有事件/模型. 未知的非空自定义名称 支持; 256 KiB以上的畸形信封和尸体被拒绝.

## 交付和回收

独一无二 `(tenant, subscription, event ID)` 发件箱行及其工作顺序 在一个数据库交易中。 重复发送 是一个不OP 该身份. 工作只包含运行时间,不透明租户/交货身份证,以及重播一代. 五次尝试使用工作 指数重试(1次初始延迟,乘数2,5分钟上限). 送货 租赁防止重叠的HTTP尝试;到期的租赁允许收回 在工人死亡之后, 终端写入需要当前租赁符 。 已禁用 订阅取消未发送的交货。 秘密在交货时被读取,所以 轮换适用于随后的尝试.

打电话 `store.reconcile()` 从一个租户的操作员 扫荡到疲惫 或取消任务为可重复播放的失败交付。 管理员刷新也运行 调和. `admin.replay(id)` 在解剖学上只为失败者创造新的工作 发送; 重复重放是无操作 。 交付的事件从此不再重播 API (英语). 接收者 **必须复制 `x-smrt-delivery`**: 如果 HTTP 成功和 程序在结果承诺之前死亡,恢复可以发出同样的请求 再来一次 包件并不完全声称HTTP效应.

## 担保合同

只有HTTPS端口443是允许的,没有证书或碎片. 都解决了 DNS地址必须是公开的独播. 套接字的搜索被锁定到一个有效的 回答时 TLS 仍在验证原始主机名 。 方向和连接 集合被禁用 。 DNS和请求的最后期限为5和10秒. 特别, 私自、绘图、过渡和文献 拒绝。 反应机构从来没有缓冲或记录。 传输覆盖是 (单位:千美元) **信任的仅服务器集成连接** 并且必须维护这些要求.

`x-smrt-signature` 实值 `sha256=<hex HMAC-SHA256(secret, timestamp + '.' + body)>`, (中文(简体) ), 时间戳是准确的 `x-smrt-timestamp` 头和身体是准确的 持续的UTF-8请求机构。 在固定时间、约束时间戳年龄和 复制送货证. `verifyWebhookSignature({ secret, body, timestamp, signature, toleranceMs? })` 常时比较和5分钟 重放窗口( 密钥可能是旋转时的一个阵列; 发送者以一个秘密标记 ; `body` 可能是一个字符串或 `Uint8Array`; 时间戳必须是发射的 `YYYY-MM-DDTHH:mm:ss.sssZ` 表格)和返回 `{ ok: true }` 或者说 `{ ok: false, reason: 'malformed' | 'expired' | 'mismatch' }`· ; `signWebhookPayload` 是匹配的标志。 键需要至少32个字节的含py 秘密材料(以密码方式生成它们;长度本身不是 en).

秘密和有效载荷是持久的敏感数据:使用受保护的数据库访问, 备份和加密在休息。 绝不将模型实例序列化 `toJSON` 客户端; 使用管理员服务或 `toPublicJSON`管理视图省略了秘密, 有效载荷和租赁信使,运输出错是固定的安全串.

## 管理用户界面和配方

`WebhookAdmin` 从 `/svelte` 使用smrt-ui按钮,卡,输入和提醒原始. 供应 `subscriptions`, (中文(简体) ), `deliveries`自动自动 `onCreate`, (中文(简体) ), `onToggle`, (中文(简体) ), `onReplay` 由 `WebhookAdminService`。在变异后刷新视图. 主机拥有登录,管理员权限,以及CSRF保护. 构成部分 有繁忙/过度的状态, 从来没有收到持续签名的秘密.

这个 `integrations.webhooks` 食谱声明 `runtime: 'server'` 编辑 `@happyvertical/smrt-webhooks/svelte#WebhookAdmin` 设置面板 融合集团. 主办方决定出口和供应经认证的 以上描述的回调和安全读取模型。 它故意宣布不 模型导航: 生成的 CRUD 已禁用, 用于这些敏感的内部 模特们 它宣布不提供或演示种子,因为运输配置和 签名机密属于服务器; 选择食谱不配置 工作或授权浏览器发送webhooks。 浏览器容量门 记录此针对 # 3717 的故意服务器根; 单独的 `/svelte` 出口包括行政部分,而不是运送.

## 验证

`pnpm test` 锻炼坚固、倒置、租房、退房、租赁栏杆, 生命周期事件,编辑,HMAC和DNS pinning. `pnpm check` 财务报告和审定财务报表 `pnpm typecheck` 检查公共类型Script/Svelte合同. `pnpm test:e2e` 运行 维护了Chromium admin的交互控制。 以 `pnpm exec turbo build --filter=@happyvertical/smrt-webhooks...` 从根起.

## 常见问题

### @happyvertical/smrt-webhooks 是什么？

外出网约车订阅、签名交付和耐久重试

### 如何安装 @happyvertical/smrt-webhooks？

在项目目录运行 npm install @happyvertical/smrt-webhooks，或使用 pnpm add / yarn add / bun add。

### @happyvertical/smrt-webhooks 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @happyvertical/smrt-webhooks 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @happyvertical/smrt-webhooks 可以商用吗？

@happyvertical/smrt-webhooks 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @happyvertical/smrt-webhooks 的下载量有多少？

根据 npm 官方下载统计，@happyvertical/smrt-webhooks 在 2026/10/17 – 2026/11/15 这 30 天内被下载 13,786 次，日均约 460 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @happyvertical/smrt-webhooks 还在维护吗？

最新版本 0\.62\.1 发布于 2026/11/17（今天）；至今共发布 103 个版本，其中过去 12 个月发布了 103 个；首次发布于 2026/10/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

