.NET Core Web API如何处理外部服务的OTP回调请求

1. 定义回调数据模型 #

根据外部服务发送的回调JSON结构，创建对应的实体类，确保字段映射准确：

using System.Text.Json.Serialization;

public class OtpCallbackResponse
{
    [JsonPropertyName("otp_request_id")]
    public string OtpRequestId { get; set; }

    [JsonPropertyName("is_valid")]
    public bool IsValid { get; set; }

    [JsonPropertyName("message")]
    public string Message { get; set; }

    // 按需添加外部服务返回的其他字段
}

2. 创建回调接收控制器 #

在API项目中新增控制器，专门处理OTP回调请求：

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/otp")]
public class OtpCallbackController : ControllerBase
{
    private readonly ILogger<OtpCallbackController> _logger;

    // 注入业务所需服务（如数据库上下文、日志服务等）
    public OtpCallbackController(ILogger<OtpCallbackController> logger)
    {
        _logger = logger;
    }

    [HttpPost("callback")]
    public IActionResult ReceiveCallback([FromBody] OtpCallbackResponse callbackData)
    {
        if (!ModelState.IsValid)
        {
            _logger.LogError("回调数据格式无效: {Errors}", ModelState.Values.SelectMany(v => v.Errors));
            return BadRequest("无效的回调数据");
        }

        // 执行回调逻辑：更新用户验证状态、记录业务日志、触发后续流程等
        _logger.LogInformation("OTP验证回调已接收: 请求ID={OtpId}, 验证结果={IsValid}", 
            callbackData.OtpRequestId, callbackData.IsValid);

        // 返回成功响应，避免外部服务重复发送回调
        return Ok(new { Status = "Success", Message = "回调已处理" });
    }
}

3. 增加回调请求的安全性验证 #

为防止恶意请求，建议给回调端点添加验证机制：

• API密钥验证：要求外部服务在请求头携带预设密钥，在控制器中校验：

[HttpPost("callback")]
public IActionResult ReceiveCallback(
    [FromBody] OtpCallbackResponse callbackData, 
    [FromHeader(Name = "X-Callback-Key")] string apiKey)
{
    var validKey = Configuration["CallbackSettings:ValidApiKey"];
    if (apiKey != validKey)
    {
        _logger.LogWarning("收到未授权的回调请求");
        return Unauthorized();
    }

    // 后续业务逻辑...
}

• IP白名单：在Program.cs中配置中间件，仅允许外部服务的IP访问该端点
• 签名验证：若外部服务会对请求签名，可在接收时校验签名合法性

4. 测试回调流程 #

本地测试时，若外部服务无法直接访问本地API，可使用内网穿透工具将本地端口暴露到公网。用Postman或curl模拟回调请求：

curl -X POST https://your-public-domain/api/otp/callback \
  -H "Content-Type: application/json" \
  -H "X-Callback-Key: your-valid-api-key" \
  -d '{
    "otp_request_id": "OTP123456",
    "is_valid": true,
    "message": "OTP验证通过"
  }'

注意事项 #

• 确保回调端点返回2xx状态码（通常为200 OK），外部服务可能在收到非成功响应时重复发送回调
• 处理回调逻辑时保证幂等性：同一回调请求多次触发时，业务逻辑不会重复执行
• 记录详细的回调日志，方便后续排查问题

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