ASP.NET Boilerplate Webhook 系统实战指南:基于发布/订阅的事件通知机制

原创2026-09-22 20:16:131,681 阅读
文章标签:后端Web框架依赖注入认证鉴权企业应用

ASP.NET Boilerplate Webhook 系统实战指南:基于发布/订阅的事件通知机制

本篇技术指南围绕 ASP.NET Boilerplate(ABP)内置的 Webhook 系统展开,讲解如何通过 发布/订阅(pub/sub) 模式把应用内发生的业务事件(如"新用户注册""租户删除")实时推送给订阅方(通常是多租户场景下的各租户)。读完本文,你将掌握从 Webhook 定义、订阅管理、签名校验到事件发布与后台重试的完整闭环,并能读懂底层源码的关键调用链,直接将其落地到自己的 ABP 项目中。

Webhook 系统的定位与整体架构

Webhook 用于通知租户特定事件。ASP.NET Boilerplate 提供了一个基于 pub/sub(发布/订阅) 的 Webhook 系统:宿主(Host)或任一租户发布事件,所有已订阅该事件的租户会收到 HTTP 回调。这套能力集中在 src/Abp/Webhooks 目录,主要由以下角色组成:

角色 接口 说明
定义管理 IWebhookDefinitionManager 管理应用允许的 Webhook 定义集合(增、查、删、判重)
订阅管理 IWebhookSubscriptionManager 提供订阅/更新/删除/激活订阅的 API
事件发布 IWebhookPublisher 发布事件,向所有匹配的订阅投递
事件发送 IWebhookSender 真正发起 HTTP POST 请求并记录发送结果
后台任务 WebhookSenderJob 以后台作业方式执行发送、失败重试与自动停用
存储 IWebhookEventStore / IWebhookSubscriptionsStore / IWebhookSendAttemptStore 分别持久化事件、订阅与发送尝试记录

一次完整的 Webhook 投递流程为:发布者调用 IWebhookPublisher.PublishAsync → 将事件数据序列化并写入 WebhookEvent 存储 → 按租户分组找出所有订阅 → 为每个订阅入队一个 WebhookSenderJob 后台作业 → 作业内由 DefaultWebhookSender 携带签名头发出 HTTP POST → 将响应状态写回 WebhookSendAttempt 表,失败时按配置重试。

第一步:定义你的 Webhook(Webhook Definitions)

在使用任何 Webhook 之前,你必须先定义系统允许的 Webhook。定义一个继承自 WebhookDefinitionProvider 的类,并在 SetWebhooks 方法中通过上下文管理器添加 WebhookDefinition:

public class AppWebhookDefinitionProvider : WebhookDefinitionProvider
{
    public override void SetWebhooks(IWebhookDefinitionContext context)
    {
        context.Manager.Add(new WebhookDefinition(
            name: AppWebHookNames.NewUserRegistered,
            displayName: L("NewUserRegisteredWebhookDefinition")
        ));

        context.Manager.Add(new WebhookDefinition(
            name: AppWebHookNames.TenantDeleted,
            displayName: L("TenantDeletedWebhookDefinition"),
            description: L("DescriptionTenantDeletedWebhookDefinition"),
            featureDependency: new SimpleFeatureDependency(AppFeatures.TestCheckFeature)
        ));
    }

    private static ILocalizableString L(string name)
    {
        return new LocalizableString(name, AbpZeroTemplateConsts.LocalizationSourceName);
    }
}

WebhookDefinition(源码见 src/Abp/Webhooks/WebhookDefinition.cs)的核心参数如下:

参数 说明
Name(string,必填) Webhook 的唯一名称。必须全局唯一,可使用 IWebhookDefinitionManager.Contains 方法检测是否已存在。源码在 WebhookDefinition 构造函数中会校验名称非空,并执行 Name.Trim()。
DisplayName(ILocalizableString) 展示名称,用于界面/本地化展示。
Description(ILocalizableString) 该 Webhook 的描述信息。
FeatureDependency(IFeatureDependency) 功能依赖(Feature Dependency)。当该功能在租户上被启用时,该 Webhook 才对租户可用;所有 Webhook 对宿主(Host)始终可用。

定义好 Provider 后,必须在模块的 PreInitialize 方法中注册它(模块机制参见 Module-System):

public class AbpZeroTemplateCoreModule : AbpModule
{
    public override void PreInitialize()
    {
        Configuration.Webhooks.Providers.Add<AppWebhookDefinitionProvider>();
    }

    //...
}

从源码看,WebhookDefinitionProvider 是标记为 ITransientDependency 的抽象类(WebhookDefinitionProvider.cs)。WebhookDefinitionManager(单例)在 Initialize() 时遍历 Configuration.Webhooks.Providers 中的每个 Provider,通过 IoC 容器解析并调用其 SetWebhooks;若添加了重名的定义,会抛出 AbpInitializationException("Webhook names must be unique!"),从机制上保证了名称唯一性(见 WebhookDefinitionManager.cs)。

第二步:订阅 Webhook(Subscribe to Webhook(s))

IWebhookSubscriptionManager 提供了订阅 Webhook 的 API。典型的订阅代码如下:

private readonly IWebhookSubscriptionManager _webHookSubscriptionManager;

public WebhookAppService(IWebhookSubscriptionManager webHookSubscriptionManager)
{
    _webHookSubscriptionManager = webHookSubscriptionManager;
}

public async Task<string> AddTestSubscription()
{
    var webhookSubscription = new WebhookSubscription()
    {
        TenantId = AbpSession.TenantId,
        WebhookUri = "http://localhost:21021/MyWebHookEndpoint",
        Webhooks = new List<string>()
        {
            AppWebHookNames.NewUserRegistered,
            AppWebHookNames.TenantDeleted
        },
        Headers = new Dictionary<string, string>()
        {
            { "MyTestHeaderKey", "MyTestHeaderValue" },
            { "MyTestHeaderKey2", "MyTestHeaderValue2" }
        }
    };
    await _webHookSubscriptionManager.AddOrUpdateSubscriptionAsync(webhookSubscription);
    return webhookSubscription.Secret;
}

WebhookSubscription(源码见 src/Abp/Webhooks/WebhookSubscription.cs)的参数含义:

参数 说明
TenantId(int?,必填) 订阅方租户的唯一标识。
WebhookUri(string,必填) 你的 Webhook 接收端点地址。
Webhooks(List<string>) 订阅的 Webhook 名称列表(对应 WebhookDefinition.Name)。只有订阅了的 Webhook 事件才会被收到。
Headers(Dictionary<string, string>) 附加请求头。订阅时可额外指定,发送 Webhook 时会一并携带。
Secret(string) 私有 Webhook 密钥,用于接收方校验 Webhook 是否被篡改,切勿公开分享。该值在创建订阅时自动生成,不建议手动修改。
IsActive(bool) 订阅是否激活,构造函数默认置为 true。

一个值得注意的源码细节:WebhookSubscriptionManager 内部维护了常量 WebhookSubscriptionSecretPrefix = "whs_"。当新订阅的 Id 为默认值(新增场景)时,会调用 GuidGenerator.Create() 生成订阅 Id,并自动生成形如 whs_ + 32 位十六进制 GUID 的密钥;当 Id 已存在(更新场景)时,仅更新 WebhookUri、Webhooks、Headers,密钥保持不变。同时,订阅前后会逐个检查每个 Webhook 定义对目标租户是否可用(IsAvailableAsync),不可用则抛出 AbpAuthorizationException(见 WebhookSubscriptionManager.cs)。

校验签名(Check Signature)

ABP 目前使用 SHA256 哈希算法生成签名:用订阅密钥对 HTTP 请求体做 HMAC-SHA256,并把结果放在名为 abp-webhook-signature 的请求头中。订阅方应用收到请求后,应当对收到的 body 做同样的哈希并比对,以确认内容未被篡改:

[HttpPost]
public async Task WebHookTest()
{
    using (StreamReader reader = new StreamReader(HttpContext.Request.Body, Encoding.UTF8))
    {
        var body = await reader.ReadToEndAsync();

        if (!IsSignatureCompatible("whs_YOURWEBHOOKSECRET", body))//read webhooksecret from user secret
        {
            throw new Exception("Unexpected Signature");
        }
        //It is certain that Webhook has not been modified.
    }
}

private bool IsSignatureCompatible(string secret, string body)
{
    if (!HttpContext.Request.Headers.ContainsKey("abp-webhook-signature"))
    {
        return false;
    }

    var receivedSignature = HttpContext.Request.Headers["abp-webhook-signature"].ToString().Split("=");//will be something like "sha256=whs_XXXXXXXXXXXXXX"
    //It starts with hash method name (currently "sha256") then continue with signature. You can also check if your hash method is true.

    string computedSignature;
    switch (receivedSignature[0])
    {
        case "sha256":
            var secretBytes = Encoding.UTF8.GetBytes(secret);
            using (var hasher = new HMACSHA256(secretBytes))
            {
                var data = Encoding.UTF8.GetBytes(body);
                computedSignature = BitConverter.ToString(hasher.ComputeHash(data));
            }
            break;
        default:
            throw new NotImplementedException();
    }
    return computedSignature == receivedSignature[1];
}

服务端生成签名头的方式可在源码中得到印证:WebhookManager.cs 中定义了 SignatureHeaderName = "abp-webhook-signature"、SignatureHeaderKey = "sha256",并按照 "sha256={0}" 模板把 BitConverter.ToString(sha256) 的结果写入请求头。由于签名以 sha256=... 格式携带算法名,接收方也可以先解析出哈希算法再决定如何计算,便于未来算法升级。

第三步:发布 Webhook(Publish Webhooks)

IWebhookPublisher 用于发布 Webhook。发布时会向当前租户的所有订阅发送事件;如果没有订阅,则不做任何事。

public class AppWebhookPublisher : DomainService, IAppWebhookPublisher
{
    private readonly IWebhookPublisher _webHookPublisher;

    public AppWebhookPublisher(IWebhookPublisher webHookPublisher)
    {
        _webHookPublisher = webHookPublisher;
    }

    public async Task NewUserRegisteredAsync(User user)
    {
        await _webHookPublisher.PublishAsync(AppWebHookNames.NewUserRegistered,
            new
            {
                UserName = user.UserName,
                EmailAddress = user.EmailAddress
            }
        );
    }

    public async Task OnMyDataChanged(MyDataChangedInput myDataChangedInput)
    {
        await _webHookPublisher.PublishAsync(AppWebHookNames.OnDataChanged, myDataChangedInput);
    }
}

如果需要把 Webhook 发送给指定租户,可以通过设置租户 Id 来实现:

await _webHookPublisher.PublishAsync(AppWebHookNames.OnDataChanged, myDataChangedInput, 5);//sends webhook(s) to subscriptions of the tenant whose id is 5

await _webHookPublisher.PublishAsync(AppWebHookNames.TenantDeleted, tenantDeletedInput, null);//sends webhook(s) to subscriptions of host

从 IWebhookPublisher.cs 的接口定义可以看到,发布方法有同步/异步两套,且都提供三个目标维度:当前租户、单个指定租户、多个指定租户(int?[] tenantIds)。方法还带一个 sendExactSameData 参数:

  • false(默认,推荐):发送时把数据包装进 WebhookPayload(含 Id、WebhookEvent、Attempt、Data、CreationTimeUtc 等元信息,见 WebhookPayload.cs),方便接收方识别事件来源与重试次数;
  • true:把传入的 data 原样序列化发送,不包装。

自定义/覆盖请求头

如前所述,用户可以为订阅定义请求头。但有时你想用统一的头发送所有 Webhook,或者需要替换/追加用户的头。这时可以使用 Publish 方法中的 headers 参数:

await _webhookPublisher.PublishAsync(AppWebhookDefinitionNames.Users.Created, data,
  headers: new WebhookHeader()
  {
      UseOnlyGivenHeaders = false,
      Headers = new Dictionary<string, string>()
      {
          {"Key1", "Value1"},
          {"Key3", "Value3"}
      }
  }
);

注意事项(WebhookHeader 定义见 src/Abp/Webhooks/WebhookHeader.cs):

  • 如果订阅中已存在同名的头,以发布时传入的头为准(发布者传入的头会覆盖订阅头)。
  • 若 UseOnlyGivenHeaders 为 true,Webhook 将只包含传入的头;若为 false,传入的头会追加到订阅预定义的头中(默认值为 false)。

该合并逻辑在 DefaultWebhookPublisher.cs 中实现:先取订阅自带的 Headers,若发布者传入了 WebhookHeader 且 UseOnlyGivenHeaders 为 true 则直接替换为给定头,否则逐个把给定头覆盖/合并进订阅头,最后连同 WebhookSenderArgs 一起入队后台作业。

第四步:Webhook 配置(Configuration)

Webhook 的全局配置项如下(接口见 IWebhooksConfiguration.cs,默认值见 WebhooksConfiguration.cs):

参数 说明 默认值(源码)
TimeoutDuration(TimeSpan) HttpClient 超时时间。WebhookSender 在抛超时异常前会等待 TimeoutDuration,之后该次 Webhook 被视为发送失败。 TimeSpan.FromSeconds(60)
MaxSendAttemptCount(int) IWebhookPublisher 在收到 HttpStatusCode.OK 之前最多尝试重发的次数。 5
JsonSerializerOptions(JsonSerializerOptions) 将 Webhook 数据转换为 JSON 时使用的序列化设置。若为 null 则使用默认设置(对应 JsonExtensions.ToJsonString)。 null
Providers(WebhookDefinitionProvider 类型列表) Webhook 定义提供者集合。 空
IsAutomaticSubscriptionDeactivationEnabled(bool) 启用后,订阅若连续失败 MaxConsecutiveFailCountBeforeDeactivateSubscription 次会被自动停用,租户需手动重新激活。 false
MaxConsecutiveFailCountBeforeDeactivateSubscription(int) 在启用自动停用时,触发停用所需的连续失败次数。 MaxSendAttemptCount × 3(即 15)

配置在模块的 PreInitialize 中完成,例如:

public class AbpZeroTemplateCoreModule : AbpModule
{
    public override void PreInitialize()
    {
        Configuration.Webhooks.TimeoutDuration = TimeSpan.FromSeconds(30);
        Configuration.Webhooks.MaxSendAttemptCount = 3;
        //...
    }
}

说明:当前仓库源码已将 JSON 序列化设置统一为 .NET 内置的 System.Text.Json.JsonSerializerOptions(原文档及早期版本使用的是 Newtonsoft 的 JsonSerializerSettings,若你基于旧版本升级,需要注意这一 API 变化)。该设置在 DefaultWebhookPublisher.SaveAndGetWebhook 序列化事件数据、以及 WebhookManager 构建发送 body 时都会被用到。

第五步:自动停用订阅(Auto Subscription Deactivation)

Webhook 内置了自动停用订阅功能。当某个订阅的端点长时间不可达时,如果一直重试会造成资源浪费;启用自动停用后,一旦订阅连续失败达到 MaxConsecutiveFailCountBeforeDeactivateSubscription 次,该订阅会被自动置为非激活状态,直到租户手动重新激活。

public class AbpZeroTemplateCoreModule : AbpModule
{
    public override void PreInitialize()
    {
        Configuration.Webhooks.IsAutomaticSubscriptionDeactivationEnabled = true;//default false
        Configuration.Webhooks.MaxConsecutiveFailCountBeforeDeactivateSubscription = 15;

        //if an endpoint fails 15 times consecutively, the subscription will be inactive.
        //default value of MaxConsecutiveFailCountBeforeDeactivateSubscription is MaxSendAttemptCount x 3
    }
    //...
}

这条链路在 WebhookSenderJob.cs 中有完整实现,值得展开:

  1. 非 TryOnce 模式下,作业先通过 IWebhookSendAttemptStore.GetSendAttemptCountAsync 统计当前发送尝试次数,若已超过 MaxSendAttemptCount 则直接放弃(不再重试)。
  2. 调用 _webhookSender.SendWebhookAsync(args) 真正发送。
  3. 若发送抛异常,则检查是否开启了自动停用;若开启,调用 HasXConsecutiveFailAsync 判断是否已连续失败 MaxConsecutiveFailCountBeforeDeactivateSubscription 次。
  4. 达到阈值后,在一个显式设置租户上下文的 UoW 中调用 ActivateWebhookSubscriptionAsync(subscriptionId, false) 停用订阅(作业运行在无环境租户的后台线程,因此需要 SetTenantId 指定租户以正确过滤)。
  5. 若未达到阈值且未停用,则重新抛出异常,让后台作业框架按队列机制继续重试。

另外,WebhookSenderArgs 还提供 TryOnce 标志:为 true 时只尝试发送一次,不检查发送次数、不参与自动停用逻辑,适用于一次性投递场景(见 WebhookSenderArgs.cs)。

底层数据表结构(Tables)

Webhook 系统依赖三张核心表(对应实体见 src/Abp/Webhooks 目录):

WebHookSubscriptionInfo(表名 AbpWebhookSubscriptions,实体 WebhookSubscriptionInfo.cs)

存储 Webhook 订阅。标注了 [MultiTenancySide(MultiTenancySides.Host)],即订阅数据归宿主管理;Webhooks 与 Headers 字段分别以 JSON 字符串存储订阅的 Webhook 名称列表与附加头字典。源码建议通过 WebhookSubscriptionInfoExtensions 中的 GetSubscribedWebhooks、SubscribeWebhook、UnsubscribeWebhook、AddWebhookHeader 等方法修改这两个字段,不要直接手工改动。

WebhookEvent(表名 AbpWebhookEvents,实体 WebhookEvent.cs)

存储已创建的事件数据。例如新用户创建并发布 Webhook 时,会创建一条 WebhookEvent(记录 WebhookName 与序列化后的 Data),随后使用这份数据向所有已订阅的租户发送。DefaultWebhookPublisher 在发布时按租户分组,每个租户组只创建一条事件记录,再为组内每个订阅各入队一个发送作业。

WebhookSendAttempt(表名 AbpWebhookSendAttempts,实体 WebhookSendAttempt.cs)

存储每次发送尝试的结果。每一行记录一次"将某条 WebhookEvent 发送给某租户订阅"的尝试,包含 WebhookEventId、WebhookSubscriptionId 外键,以及端点返回的 Response 内容与 ResponseStatusCode 状态码。DefaultWebhookSender 在发送前先 InsertAndGetIdWebhookSendAttemptAsync 建立尝试记录,结束后通过 StoreResponseOnWebhookSendAttemptAsync 回写状态码与响应内容,超时场景下状态码会记录为 HttpStatusCode.RequestTimeout。

发送链路源码速览

IWebhookPublisher 的默认实现是 DefaultWebhookPublisher(src/Abp/Webhooks/DefaultWebhookPublisher.cs),IWebhookSender 的默认实现是 DefaultWebhookSender(src/Abp/Webhooks/DefaultWebhookSender.cs),二者协同完成一次投递:

  1. DefaultWebhookPublisher.PublishAsync 查询具备功能授权的订阅集合(GetAllSubscriptionsIfFeaturesGrantedAsync),无订阅则直接返回;有订阅则按租户分组,为每个租户生成并持久化一条 WebhookEvent。
  2. 为每条订阅组装 WebhookSenderArgs(含目标 URI、密钥、合并后的头、事件 Id 等),通过 IBackgroundJobManager.EnqueueAsync<WebhookSenderJob, WebhookSenderArgs> 入队后台作业,保证发布方法快速返回、发送异步执行。
  3. WebhookSenderJob 校验发送次数上限后调用 DefaultWebhookSender.SendWebhookAsync。
  4. DefaultWebhookSender 创建 HttpClient(Timeout 取 TimeoutDuration)发起 POST;WebhookManager 负责序列化 body、用订阅密钥计算 HMAC-SHA256 签名并写入 abp-webhook-signature 头;附加头则通过 AddAdditionalHeaders 逐个尝试写入请求头或内容头。
  5. 只有收到 2xx 响应(IsSuccessStatusCode)才算成功,否则抛出异常触发后台重试,直到达到 MaxSendAttemptCount 上限或触发订阅自动停用。

小结

至此,你已经掌握了 ASP.NET Boilerplate Webhook 系统的完整使用路径:定义(WebhookDefinitionProvider)→ 注册(Configuration.Webhooks.Providers)→ 订阅(IWebhookSubscriptionManager)→ 校验(SHA256 签名)→ 发布(IWebhookPublisher)→ 配置(超时/重试/自动停用)→ 落库(三张 Webhook 表)。这套机制非常适合在多租户 SaaS 应用中向租户异步推送业务事件,其"事件持久化 + 后台作业投递 + 签名校验 + 失败重试与自动停用"的设计也为你自行扩展更复杂的推送场景(如自定义重试策略、事件回放)提供了清晰的源码级参考。

登录后查看全文
aspnetboilerplate