寻求ASP.NET WebHooks接收Vend API WebHook的C#实现方案

我完全懂你现在的困境——官方的ASP.NET WebHooks接收器都是为GitHub、Instagram这类平台量身定做的，那个Custom接收器也只适配ASP.NET生态内的自定义WebHook格式，对Vend这种第三方自定义WebHook确实不太友好。其实不用纠结那些现成的接收器，我们可以直接基于ASP.NET Core的API控制器来实现一个轻量、适配Vend的WebHook端点，步骤很清晰：

1. 先明确Vend WebHook的核心要求 #

Vend的WebHook推送有几个关键点：

• 请求方式：POST
• 请求体：JSON格式的事件数据
• 签名验证：请求头里的X-Vend-Signature是Vend用你的API密钥对请求体做HMAC-SHA256加密后的结果，必须验证这个签名确保请求来自Vend
• 响应要求：成功接收后必须返回200 OK，否则Vend会重试

2. 创建WebHook接收控制器 #

新建一个API控制器，专门处理Vend的WebHook请求：

using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

[ApiController]
[Route("api/webhooks/vend")]
public class VendWebHookController : ControllerBase
{
    private readonly string _vendApiKey;

    public VendWebHookController(IConfiguration configuration)
    {
        // 从配置文件读取你的Vend API密钥（建议存在appsettings.json或环境变量里）
        _vendApiKey = configuration["Vend:ApiKey"] ?? throw new ArgumentNullException(nameof(_vendApiKey));
    }

    [HttpPost]
    public async Task<IActionResult> ReceiveWebHook()
    {
        // 启用请求体缓冲，因为我们需要多次读取（验证签名+解析内容）
        Request.EnableBuffering();

        // 第一步：验证签名
        var isSignatureValid = await ValidateVendSignatureAsync(Request, _vendApiKey);
        if (!isSignatureValid)
        {
            // 签名验证失败，返回403禁止访问
            return Forbid();
        }

        // 第二步：解析请求体的事件数据
        Request.Body.Position = 0; // 重置流指针到开头
        var eventData = await JsonSerializer.DeserializeAsync<VendWebHookEvent>(Request.Body);
        if (eventData == null)
        {
            return BadRequest("Invalid event data");
        }

        // 第三步：根据事件类型处理业务逻辑
        switch (eventData.Type)
        {
            case "product.created":
                HandleProductCreated(eventData.Data);
                break;
            case "sale.completed":
                HandleSaleCompleted(eventData.Data);
                break;
            // 其他Vend事件类型按需添加
            default:
                // 处理未知事件
                break;
        }

        // 返回200 OK告知Vend已成功接收
        return Ok();
    }

    // 签名验证核心方法
    private async Task<bool> ValidateVendSignatureAsync(HttpRequest request, string apiKey)
    {
        if (!request.Headers.TryGetValue("X-Vend-Signature", out var signatureHeader))
        {
            return false;
        }

        var requestBody = await new StreamReader(request.Body).ReadToEndAsync();
        request.Body.Position = 0; // 重置指针供后续解析

        // 用API密钥对请求体做HMAC-SHA256加密
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiKey));
        var hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(requestBody));
        var computedSignature = BitConverter.ToString(hashBytes).Replace("-", "").ToLowerInvariant();

        // 对比计算出的签名和请求头里的签名
        return computedSignature.Equals(signatureHeader.ToString(), StringComparison.OrdinalIgnoreCase);
    }

    // 示例：处理商品创建事件
    private void HandleProductCreated(JsonElement productData)
    {
        // 这里写你的业务逻辑，比如把商品数据同步到本地数据库
        var productId = productData.GetProperty("id").GetString();
        var productName = productData.GetProperty("name").GetString();
        // ...
    }

    // 示例：处理销售完成事件
    private void HandleSaleCompleted(JsonElement saleData)
    {
        // 销售完成后的业务逻辑
        var saleId = saleData.GetProperty("id").GetString();
        var totalAmount = saleData.GetProperty("total").GetDecimal();
        // ...
    }
}

// 定义Vend WebHook事件的基础结构
public class VendWebHookEvent
{
    [JsonPropertyName("type")]
    public string Type { get; set; } = string.Empty;

    [JsonPropertyName("data")]
    public JsonElement Data { get; set; }
}

3. 配置与部署注意事项 #

• API密钥存储：不要硬编码API密钥，建议放在appsettings.json里，生产环境用环境变量或密钥管理器：

  {
    "Vend": {
      "ApiKey": "your-vend-api-key-here"
    }
  }
  

• 请求体缓冲：一定要调用Request.EnableBuffering()，否则第一次读取请求体后，流就到末尾了，后续解析会失败。
• Vend平台配置：在Vend后台的WebHook设置里，把你的控制器地址（比如https://your-domain/api/webhooks/vend）填进去，确保Vend能访问到你的端点（如果是本地开发，可能需要用内网穿透工具做映射）。
• 重试机制：如果你的处理逻辑可能耗时较长，建议把事件放入消息队列（比如RabbitMQ、Azure Service Bus）异步处理，避免长时间占用请求导致Vend重试。

4. 可选优化：把签名验证抽成过滤器 #

如果多个地方需要验证Vend签名，可以把验证逻辑做成一个Action Filter，这样控制器代码更简洁：

public class VendWebHookSignatureFilter : IAsyncActionFilter
{
    private readonly IConfiguration _configuration;

    public VendWebHookSignatureFilter(IConfiguration configuration)
    {
        _configuration = configuration;
    }

    public async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
    {
        var request = context.HttpContext.Request;
        var apiKey = _configuration["Vend:ApiKey"];
        var isSignatureValid = await ValidateVendSignatureAsync(request, apiKey);

        if (!isSignatureValid)
        {
            context.Result = new ForbidResult();
            return;
        }

        await next();
    }

    // 这里复用之前的ValidateVendSignatureAsync方法
    private async Task<bool> ValidateVendSignatureAsync(HttpRequest request, string apiKey)
    {
        // 实现和之前一样的签名验证逻辑
    }
}

然后在控制器上添加过滤器：

[ServiceFilter(typeof(VendWebHookSignatureFilter))]
[ApiController]
[Route("api/webhooks/vend")]
public class VendWebHookController : ControllerBase
{
    // 控制器代码可以去掉签名验证部分，更简洁
}

这个方案完全自定义，适配Vend的WebHook格式，不用依赖那些不兼容的官方接收器，灵活性也很高，你可以根据自己的业务需求调整处理逻辑。

内容的提问来源于stack exchange，提问作者Yusha