解析Stripe webhook事件时触发System.NullReferenceException错误

问题场景 #

开发了处理Stripe checkout.session.completed事件的Webhook，调用EventUtility.ParseEvent(json)时抛出System.NullReferenceException，最初无法定位原因，最终排查出是使用了错误的JSON payload格式。

错误触发代码行 #

var stripeEvent = EventUtility.ParseEvent(json); // 此处抛出NullReferenceException

Webhook核心代码示例 #

[HttpPost("stripe-webhook")]
public async Task<IActionResult> StripeWebhook()
{
    var json = await new StreamReader(HttpContext.Request.Body).ReadToEndAsync();
    try
    {
        var stripeEvent = EventUtility.ParseEvent(json); // 错误触发点
        if (stripeEvent.Type == Events.CheckoutSessionCompleted)
        {
            var session = stripeEvent.Data.Object as Session;
            // 后续业务逻辑处理
        }
        return Ok();
    }
    catch (Exception ex)
    {
        return BadRequest($"Webhook Error: {ex.Message}");
    }
}

原始错误Payload示例（从Stripe Dashboard获取的错误格式） #

注：此处为错误的Payload，仅传入了Checkout Session对象而非完整的Stripe Event结构

{
  "id": "cs_test_xxx",
  "object": "checkout.session",
  "payment_status": "paid",
  // 其他Session字段...
}

正确的Stripe Event Payload格式示例 #

{
  "id": "evt_xxx",
  "object": "event",
  "api_version": "2024-06-20",
  "created": 1718923456,
  "data": {
    "object": {
      "id": "cs_test_xxx",
      "object": "checkout.session",
      "payment_status": "paid",
      // 其他Checkout Session字段...
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": {
    "id": null,
    "idempotency_key": "xxx"
  },
  "type": "checkout.session.completed"
}

问题原因与解决 #

EventUtility.ParseEvent需要接收完整的Stripe Event结构，而非单独的Checkout Session对象。错误Payload仅传入了Session数据，缺少外层的Event包装（比如id、object: "event"、type等核心字段），导致解析时内部逻辑因找不到必要字段触发NullReferenceException。

解决方式：确保Webhook接收的是Stripe官方推送的完整Event JSON，而非自行截取的Session片段；测试时从Stripe Dashboard的Events页面复制完整的Event JSON作为测试Payload。

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