Webhook 示例服务

本项目用于演示如何获取设备主动上报信息等，便于客户更快地将 API 接入自己的业务系统。

部署环境

• JDK 25
• GraalVM Community 25.0.2（用于原生编译）
• Gradle Wrapper（使用仓库内置 ./gradlew）
• MinIO 或兼容 S3 的对象存储服务

启动

./gradlew bootRun

服务默认监听端口：

8181

原生编译

./gradlew clean nativeCompile --refresh-dependencies --no-daemon
./build/native/nativeCompile/webhook-sample

上报信息类接口

上报信息类接口使用统一请求格式：

{
  "timestamp": 1710000000000,
  "retry": 0,
  "message": "previous failure reason",
  "device_sn": "xxx",
  "data": {}
}

字段说明：

字段	类型	是否必填	说明
timestamp	number	是	服务端发送 webhook 时的毫秒时间戳
retry	number	是	当前重试次数，首次请求为 0
message	string	否	仅重试时可能出现，表示上一次 webhook 请求失败原因
device_sn	string	是	触发该 webhook 的设备 SN
data	object	是	业务数据，不同 webhook path 结构不同

重试规则：

最多发送 3 次，retry 取值为 0、1、2，即首次请求 1 次加重试 2 次。如果第一次失败，第二次请求会带上一次失败原因：

{
  "timestamp": 1710000000000,
  "retry": 1,
  "message": "previous webhook request failed",
  "device_sn": "xxx",
  "data": {}
}

成功响应：

{
  "code": 0,
  "data": null,
  "message": "success"
}

方法	路径	功能
POST	/webhook/events/cover-open	舱盖打开进度回调，打印 event_id、result、percent、result_message
POST	/webhook/events/cover-close	舱盖关闭进度回调，打印 event_id、result、percent、result_message
POST	/webhook/events/charge-open	充电打开进度回调，打印 event_id、result、percent、result_message
POST	/webhook/events/charge-close	充电关闭进度回调，打印 event_id、result、percent、result_message
POST	/webhook/events/drone-open	飞行器舱门打开进度回调，打印 event_id、result、percent、result_message
POST	/webhook/events/drone-close	飞行器舱门关闭进度回调，打印 event_id、result、percent、result_message
POST	/webhook/events/device/hms	设备 HMS 告警回调，打印 device_sn 和 data.list[].message
POST	/webhook/events/sub-device/hms	子设备 HMS 告警回调，打印 device_sn 和 data.list[].message
POST	/webhook/events/file-upload-callback	文件上传完成回调，打印 event_id 和 file.name
POST	/webhook/events/flighttask-progress	航线任务进度回调，打印 event_id 和 percent；当 result != 0 时额外打印 message。执行任务必须实现
POST	/webhook/osd/device	接收设备 OSD 数据，返回成功响应
POST	/webhook/osd/sub-device	接收子设备 OSD 数据，返回成功响应

请求查询类接口

方法	路径	功能
GET	/webhook/requests/storage-config-get?module=1&device-sn=xxx	返回对象存储上传配置，包含 device_sn、bucket、endpoint、region、object_key_prefix 和临时 credentials。回传媒体必须实现
GET	/webhook/requests/flighttask-resource-get?event-id=xxx	返回航线文件 sample.kmz 的 fingerprint 和预签名下载 url。执行任务必须实现