C#实现PayPal Webhook验签始终返回false如何排查解决?
C# 实现PayPal Webhook签名校验失败的核心原因
问题背景
基于C#搭建服务接收PayPal Webhook通知时,需要实现符合官方规范的签名校验逻辑才能确认请求合法性。此前检索到的同主题技术提问均未覆盖核心实现细节,无法直接复现可运行的校验流程。
当前已实现的校验代码如下:
public static bool Validate(X509Certificate2 x509Certificate, WebhookSignature webhookSignature) { bool isValid = false; try { byte[] webhookBodyByte = Encoding.UTF8.GetBytes(webhookSignature.webhook_event); uint crc32 = Crc32CAlgorithm.Compute(webhookBodyByte); var expectedSignature = string.Format("{0}|{1}|{2}|{3}", webhookSignature.transmission_id, webhookSignature.transmission_time, webhookSignature.webhook_id, crc32); byte[] expectedSignatureBytes = Encoding.UTF8.GetBytes(expectedSignature); byte[] signatureBytes = Convert.FromBase64String(webhookSignature.transmission_sig); using (RSA rsa = x509Certificate.GetRSAPublicKey()) { isValid = rsa.VerifyData(expectedSignatureBytes, signatureBytes, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1); } } catch (Exception ex) { throw ex; } return isValid; }
核心问题定位
执行校验时rsa.VerifyData方法始终返回失败,根因可归纳为三点:
- CRC32计算的输入源不符合规范
按照PayPal的官方签名规则,CRC32C校验的输入是收到HTTP请求时的原始字节流,不能将请求体反序列化为对象、再重新序列化为字符串后计算。这类二次序列化的操作往往会改变JSON的空格、字段顺序、特殊字符编码,导致计算出的校验值和PayPal侧计算的结果完全不一致。 - CRC32结果的格式不符合要求
PayPal侧拼接待签名串时,会将计算得到的CRC32C无符号整数,转换为8位长度的小写十六进制字符串(不足位时前方补0)。而现有代码是直接将uint类型的CRC值转换为十进制字符串拼接,两种格式生成的待签名串存在本质差异,最终导致公钥校验签名永远无法匹配。 - 异常捕获逻辑存在瑕疵
代码中catch块直接使用throw ex抛出异常,会重置原始异常的堆栈跟踪信息,排查问题时难以定位真实错误位置,建议改为无参数的throw语句,保留完整调用栈信息。
正确的校验实现流程
完整的可运行校验逻辑需要遵循以下固定步骤:
- 从请求头中提取所有校验必需的字段:
Paypal-Transmission-Id:单次请求的唯一传输标识Paypal-Transmission-Time:请求推送的ISO8601格式时间Paypal-Cert-Url:官方指定的验签公钥证书地址Paypal-Auth-Algo:签名使用的哈希算法(通用为SHA256)Paypal-Transmission-Sig:Base64编码的PayPal签名值
- 在管道读取请求内容时,直接留存原始请求的字节数组,全程不做字符串转换、对象反序列化操作,从根源保证计算CRC的字节流和PayPal推送的原始内容完全一致。
- 对原始字节流执行CRC32C计算,将得到的无符号整数转换为8位长度的小写十六进制字符串,作为拼接串的最后一段。
- 按照固定顺序拼接待签名原文:
{transmission_id}|{transmission_time}|{在PayPal后台配置的Webhook固定ID}|{十六进制格式的CRC32C值}。注意这里的Webhook ID是创建Webhook时PayPal分配的固定标识,不是请求体里携带的事件ID。 - 从官方指定的证书地址获取X509证书,提取证书中的RSA公钥,用请求头指定的哈希算法,对Base64解码后的签名值做校验,匹配则代表请求合法。
参考样例
收到的Webhook请求体示例
{"id":"WH-9UD89617J3011950R-48P38622S7224850U","event_version":"1.0","create_time":"2021-04-12T13:48:33.815Z","resource_type":"checkout-order","resource_version":"2.0","event_type":"CHECKOUT.ORDER.APPROVED","summary":"An order has been approved by buyer","resource":{"create_time":"2021-04-12T13:47:55Z","purchase_units":[{"reference_id":"default","amount":{"currency_code":"EUR","value":"300.00"},"payee":{"email_address":"sb-6g4h15347490@business.example.com","merchant_id":"6WHMHKSMV4T4E","display_data":{"brand_name":"ieQ Shop"}},"shipping":{"name":{"full_name":"test buyer"},"address":{"address_line_1":"ESpachstr. 1","admin_area_2":"Freiburg","admin_area_1":"Empty","postal_code":"79111","country_code":"DE"}}}],"links":[{"href":"https://api.sandbox.paypal.com/v2/checkout/orders/2PY82104UY468500C","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v2/checkout/orders/2PY82104UY468500C","rel":"update","method":"PATCH"},{"href":"https://api.sandbox.paypal.com/v2/checkout/orders/2PY82104UY468500C/capture","rel":"capture","method":"POST"}],"id":"2PY82104UY468500C","intent":"CAPTURE","payer":{"name":{"given_name":"test","surname":"buyer"},"email_address":"rasheed.alsamawi-buyer@gmail.com","payer_id":"WQRMLHUWJA7H4","address":{"address_line_1":"Strasse Nummer X","address_line_2":"Strasse Nummer X","admin_area_2":"admin 2","admin_area_1":"admin 1","postal_code":"12345","country_code":"DE"}},"status":"APPROVED"},"links":[{"href":"https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9UD89617J3011950R-48P38622S7224850U","rel":"self","method":"GET"},{"href":"https://api.sandbox.paypal.com/v1/notifications/webhooks-events/WH-9UD89617J3011950R-48P38622S7224850U/resend","rel":"resend","method":"POST"}]}
请求头包含所有校验必需的标识字段,可参考实际抓取的请求截图核对字段完整性。
内容的提问来源于stack exchange,提问作者Rasheed
相关产品推荐
相关产品推荐

