Spring Boot实现的Twilio状态回调URL未被调用问题排查咨询

1. ad-hoc房间回调的常见认知误区 #

你遇到的最典型配置错误就是：Twilio控制台默认的房间回调配置不会自动对客户端创建的ad-hoc房间生效。ad-hoc房间的状态回调需要满足以下任意一个配置要求：

• 进入Twilio控制台的「Video > 设置 > 通用 > 默认房间设置」，提前配置全局默认的状态回调URL、回调HTTP方法、需要触发的回调事件列表，所有新创建的ad-hoc房间会自动继承这个默认配置
• 如果是通过客户端代码显式创建ad-hoc房间，需要在创建参数中传入StatusCallback、StatusCallbackMethod、StatusCallbackEvent指定回调配置，不过ad-hoc模式下客户端通常没有权限传递这类服务端配置参数，更推荐走全局默认配置方案。

2. 服务端接口的配置遗漏问题 #

• 你的@PostMapping没有指定接口路径，确认Twilio后台填写的回调URL是对应这个接口的完整公网路径，如果路径不匹配会直接被服务端拦截，不会进入接口逻辑。
• 你将所有参数都设置为了必填的@RequestParam，但Twilio的回调请求不会在所有事件下都携带你列出的全部参数：比如participant-connected事件不会返回ParticipantDuration、RoomDuration这类只有结束事件才会携带的参数，Spring检测到缺少必填参数会直接返回400错误，Twilio收到错误后可能会停止重试推送。你需要给非全事件通用的参数加上required = false属性，避免参数校验拦截合法请求。
• 确认你的服务部署地址是公网可访问的，Twilio的回调请求从公网发起，无法访问localhost、192.168开头的内网地址，本地开发阶段需要用内网穿透工具将本地端口暴露到公网，再将穿透后的公网地址填写到Twilio后台。
• 检查Spring Boot是否开启了CSRF跨站请求伪造拦截，默认开启的CSRF校验会直接拦截Twilio发来的POST请求，你需要给回调接口所在的路径放行CSRF校验。
• 检查服务器防火墙、云服务安全组配置，是否开放了回调接口的端口，是否拦截了Twilio的IP段请求。

3. 快速排查调试方案 #

你可以先新增一个无参数绑定的测试接口，打印所有收到的请求信息，先确认请求是否能到达你的服务端：

@PostMapping("/twilio-callback-test")
public ResponseEntity<String> testCallback(HttpServletRequest request) {
    // 打印所有请求参数
    request.getParameterMap().forEach((k, v) -> log.info("参数{}: {}", k, Arrays.toString(v)));
    // 打印所有请求头
    Collections.list(request.getHeaderNames()).forEach(h -> log.info("请求头{}: {}", h, request.getHeader(h)));
    return ResponseEntity.ok("ok");
}

将测试接口的公网地址填写到Twilio回调配置中，触发房间事件后查看是否有日志输出，确认请求能到达服务端后，再调整正式接口的参数配置即可。

内容的提问来源于stack exchange，提问作者Trọng Nghĩa Lê Đình