Alert Webhook HTTP 联动配置指南

Webhook 是什么

Webhook 就是一个 HTTP 请求——Keep Alive 触发预警的那一刻，会向你指定的 URL 发送一条 HTTP POST 请求。收到请求的那一端（可以是 Home Assistant、钉钉机器人、飞书自定义机器人、或你自己写的后端服务）就知道"Keep Alive 预警了"，然后可以执行任何动作。

这是 Keep Alive 四路预警出口里最灵活的一路——短信、电话、定位都是固定格式，但 Webhook 能接任何平台。

能做什么

典型的联动场景：

• Home Assistant 家庭自动化：收到 Webhook 后自动打开家里的灯、拉响警报、发送推送通知到所有家庭成员的手表
• 钉钉/飞书/企业微信群：把预警发到紧急联系人的工作群，确保有人看到
• 自建后端服务：把预警存到数据库、触发邮件、调用其他 API
• 智能家居联动：打开门锁（给救援人员）、启动摄像头、打开通风系统

配置方法

在主设置页找到 Alert Webhook，输入一个完整的 URL。格式示例：

https://your-server.com/keepalive/alert

⚠️ 注意：Webhook 只在有网络的情况下才能送达。如果触发预警时手机没网，Webhook 会被跳过（SMS 和电话不受影响）。这也是为什么 Lite 版本去掉了 Webhook——Lite 版也去掉了 Internet 权限。

Lite 版本和 Webhook

Lite 版本不支持 Webhook——因为 Lite 的设计目标是 F-Droid 纯网脱用户，不申请 Internet 权限。如果你需要 Webhook 联动，请用完整版（从 GitHub Releases 或 Google Play 下载）。

请求格式是什么

Keep Alive 发送的是 HTTP POST 请求，请求体是 JSON 格式。具体字段会随版本变化，但核心字段包括：

• alert_id：本次预警的唯一标识
• timestamp：触发时间戳
• location（如果开启了定位）：GPS 坐标和地址
• contacts：配置了哪些紧急联系人
• custom_message：你在 Alert Message 里写的文案

接收端可以根据这些字段做任何处理。

注意事项

1. URL 必须支持 HTTPS

Keep Alive 不会发送到 HTTP URL——出于隐私安全，必须是 HTTPS。

2. 网络权限

完整版需要 Internet 权限，在系统设置里要确保"允许使用网络"没有被禁用。

3. 不要依赖 Webhook 作为唯一预警通道

Webhook 是第四路——短信和电话是基础。如果只配了 Webhook，手机没网时预警就完全失效了。至少保留一位 SMS 联系人作为兜底。

4. 测试一下

触发一次模拟预警（1.3.3+ 支持测试功能），确认你的 Webhook 接收端真的收到了请求。

关于 Lite 版本和完整版的差异，见 Lite 版本。