@happyvertical/smrt-webhooks

中文文档
0.62.1发布于 2026/11/17TypeScriptES Module近 30 天下载 1.4万

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

中文使用文档
文档目录5 节
  1. 服务器设置
  2. 交付和回收
  3. 担保合同
  4. 管理用户界面和配方
  5. 验证

外出网点

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

服务器设置

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

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 传播等效失败; 重新保存源对象不 重建缺失的历史创建/更新事件.

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

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 共发布 103 个版本,首次发布于 2026/10/15;过去 12 个月发布了 103 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @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 和提交记录判断。