Bitzsoft.Integrations.Webhooks 1.0.0-alpha.10

Bitzsoft.Integrations.Webhooks

跨 net5.0、net8.0、net10.0 的 Webhook Gateway。公共模型不依赖 ASP.NET Core，因此 MVC、Minimal API、Worker、消息队列消费者可以复用同一套验签和 Inbox 状态机。

安装与兼容性

dotnet add package Bitzsoft.Integrations.Webhooks

包支持 net5.0、net8.0 和 net10.0。它不依赖 ASP.NET Core；HTTP endpoint、 响应状态码和入口容量策略由宿主负责。

已实现边界

• 复制并保留原始 bytes、查询信息和多值 Header；
• 平台不截断正文，也不强制正文大小上限；
• 按可信 WebhookRoute 隔离 tenant/provider/endpoint/region/environment；
• Provider IWebhookVerifier；
• Provider 可声明敏感 Header；验签读取原值后，Inbox 信封只持久化固定脱敏 占位符；
• 通用 HMAC-SHA256/384/512，Hex/Base64、三种签名材料模式；
• 时间窗、固定时间签名比较、轮换密钥字段；
• nonce/replay key 与 payload digest 冲突检测；
• 同时保留原始正文审计摘要和 Provider 可选的语义幂等摘要，正确处理 transport 重投元数据变化；
• CloudEvents 1.0 风格 WebhookEnvelope；
• 幂等 Inbox、排他租约、租约失效后重新获取；
• 指数重试、Provider Retry-After、DLQ 和人工重放；
• Handler 取消不计入失败，未知异常消息不进入 Inbox；
• 进程内 Adapter 只在显式调用时注册。

注册

生产宿主应注册自己的持久化 IWebhookReplayStore 和 IWebhookInboxStore：

services.AddBitzsoftWebhookGateway();
services.AddSingleton<IWebhookReplayStore, SqlWebhookReplayStore>();
services.AddSingleton<IWebhookInboxStore, SqlWebhookInboxStore>();
services.AddScoped<IWebhookEventHandler, OrderWebhookHandler>();

开发或单实例测试可显式选择内存实现：

services.AddInMemoryIntegrationCredentials();
services.AddInMemoryWebhookInfrastructure();

services.AddHmacWebhookVerifier("Orders:partner-a", options =>
{
    options.SignatureHeaderName = "X-Partner-Signature";
    options.TimestampHeaderName = "X-Partner-Timestamp";
    options.DeliveryIdHeaderName = "X-Partner-Delivery";
    options.SignaturePrefix = "sha256=";
});

AddBitzsoftWebhookGateway() 不会隐式回退到内存 Store，避免生产多实例部署 在没有共享幂等约束时看似可用。

默认情况下 WebhookEnvelope.PayloadSha256 与 IdempotencyPayloadSha256 相同。只有完成验签和严格解析后的 Provider verifier 才可调用 WithIdempotencyPayloadSha256 忽略明确的 transport 元数据差异；原始 bytes 和原始摘要不会被改写。自定义 Inbox Adapter 必须使用 IdempotencyPayloadSha256 判断同一事件 ID 的重复或冲突。

接收

宿主路由必须先通过可信的 endpoint 配置确定 tenant 和 Provider。不要根据未经验签的 正文或 Header 选择租户。

var route = new WebhookRoute(
    tenantId: tenantIdFromTrustedEndpoint,
    providerKey: "Orders:partner-a",
    endpointId: endpointId,
    region: "cn",
    environment: IntegrationEnvironments.Production);

var request = new WebhookRequest(
    rawBodyBytes,
    requestHeaders,
    httpMethod: "POST",
    requestUri: requestUri,
    queryString: queryString,
    contentType: contentType);

var result = await gateway.ReceiveAsync(route, request, cancellationToken);

• Accepted：首次写入 Inbox；
• Duplicate：相同事件 ID 和相同正文已存在，可向 Provider 返回成功；
• Rejected：签名、时间窗、replay 或幂等冲突，不应分发给 Handler。

Worker、重试与死信

var result = await processor.ProcessNextAsync(
    leaseDuration: TimeSpan.FromMinutes(2),
    cancellationToken);

Handler 应保持幂等。若抛出 WebhookProcessingException，可明确永久/瞬时失败和 RetryAfter；未知异常默认按瞬时失败处理，但异常原文不会持久化，防止 secret 进入 DLQ。

死信查询强制指定租户：

var deadLetters = await inbox.GetDeadLettersAsync(
    new WebhookDeadLetterQuery(tenantId, "Orders:partner-a"),
    maximumCount: 100,
    cancellationToken);

内存实现不适用于多实例、进程重启恢复或合规审计。生产 Adapter 必须提供数据库唯一 约束、原子租约、保留/清理策略、静态加密以及人工重放审计。