使用说明

HTTP 推送通知：一个 HTTPS 链接或 Webhook 发到手机

用私有 HTTPS 链接或 POST Webhook，把 HTTP 通知发到 iPhone 或 Android；支持文本、JSON 和表单，无需安装 CLI。

更新于 2026年10月26日

如何用 HTTP 请求把通知发到手机？

在手机 Ntfyx 复制私有 HTTPS 推送链接，访问即可发通知，也可保留 URL 不变，从自己的服务 POST 文本、JSON 或表单。无需 CLI，key 只有发送权限；服务读取输入后再为手机加密投递。

打开 Ntfyx。新收件箱会准备好 MyNotify 自定义 Topic；已有收件箱保留原来的 Topic 名称。
点击“发送”。App 通过真实远端 HTTPS 请求发送，再等待对应消息进入收件箱。
从 App 复制专属发送链接，访问即可发送，也可接入脚本或服务。

下载与版本可用状态

同一个私有 URL，GET 或 POST 都能发

在 Ntfyx 复制完整 HTTPS 推送 URL。GET 访问时发送最后路径段的消息；接入服务时保留复制地址不变，POST 文本或 JSON 的 text 字段。HTTP 通知描述的是接入方式，真实发送链接使用 HTTPS 加密传输；服务读取请求后再为手机加密投递。

curl --request POST "$NTFYX_WEBHOOK_URL" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: example-build-123" \
  --data '{"title":"Build","text":"Build complete"}'

专属发送链接

App 自动准备 https://api.ntfyx.me/v1/send/{key}/{topic}/{message}，包含简短的 sk_ key 和自己的 Topic，默认测试正文为 hello。简短 key 需要 App 1.5.2，已有版本化链接继续可用。复制完整链接或点击“发送”，访问链接即可发通知；只需将最后一段替换为编码后的消息。key 绑定原 Topic，修改 Topic 段不能向其他 Topic 发消息。下方只有占位示例，不具备发送权限。

https://api.ntfyx.me/v1/send/sk_EXAMPLE_KEY_123456789A/MyNotify/hello

复制原链接，直接用作固定 POST Webhook

从手机 HTTPS 推送复制完整链接，粘贴到第三方的 Webhook URL 一栏，选择 POST，在请求正文中发送动态消息。原来的 /hello 结尾可以保留：POST 使用 body 中的新正文；直接 GET 访问时仍按原 URL 中的消息发送。这条接入路径沿用现有 App 链接，无需为它更新商店版。

在 Ntfyx 的 HTTPS 推送中复制私有发送链接。
在第三方粘贴固定 URL，选择 POST、application/json，并提供 text 等文本字段；也可使用 text/plain。
发送测试，并在手机确认匹配消息。HTTP 已受理不能单独证明手机已收到。

POST YOUR_PRIVATE_APP_URL
Content-Type: application/json
Idempotency-Key: build-123

{"text":"Build complete"}

正文格式与重试

支持 JSON 字符串、JSON 中的 body / message / text / content、UTF-8 纯文本及 URL 编码表单（包含 payload JSON）。出现的文本别名必须为字符串且彼此同值；其他事件 JSON 转为文本展示，超过 12,000 字符返回 413，不截断。可选 title 与 Session 字段用于标题和会话。上传 body 的读取有绝对 5 秒期限，超时 408 可重试；这不是整体请求或手机投递 5 秒完成承诺。原始请求最多 64 KiB，正文 12,000 字符，标题 120 字符；最终 JSON 消息另受含 JSON 开销的 16 KiB 加密 payload 限制，多字节正文可能先触及此限；非法 UTF-8、重复 JSON/form key、冲突别名或不支持的格式会被拒绝。不抓取附件或 URL；文本字段支持不表示完整支持 Slack blocks 或 Discord embeds/files。

正文类型	示例
application/json	{"text":"构建完成"}
application/json	{"title":"部署","body":"新版已准备"}
text/plain	构建完成
application/x-www-form-urlencoded	message=Build%20complete

GitHub 失败投递说明

用 CLI 或 MCP 管理独立 Webhook key

CLI 0.3.0 与本地 MCP 可以管理独立 wh_ 发送 key。先在主手机准备 HTTPS 推送、配对 Source，再申请单独的 webhook 管理授权。手机须明确批准固定 Topic 与范围；监控授权不能用于管理 webhook。管理 grant 最长 24 小时，已创建 key 则可持续至 owner Source 到期，可能长于 grant。

ntfyx webhook authorize --async --no-input --expires 24h --json
ntfyx webhook auth-status AUTHORIZATION_ID --json
ntfyx webhook create --name "Deploy alerts" --url-file ./private-webhook-url.txt --json
ntfyx webhook list --json
ntfyx webhook show WEBHOOK_ID --json
ntfyx webhook update WEBHOOK_ID --name "Production deploys" --dry-run --json
ntfyx webhook rotate WEBHOOK_ID --url-file ./next-private-webhook-url.txt --json
ntfyx webhook disable WEBHOOK_ID --json
ntfyx webhook enable WEBHOOK_ID --json
ntfyx webhook delete WEBHOOK_ID --json
ntfyx webhook revoke --json

停止发送与撤销管理是不同操作

webhook revoke 仅撤销当前 Source 的管理 grant，不停用已创建的发送 key。停止某个 URL 请用 disable 或 delete。owner Source 撤销/过期、主手机 key/身份或 Root 版本变化会使其 key 失效。父 HTTPS 发送端暂停时子 key 同样暂停，同一父 token 恢复后可继续；父 token 轮换使旧子 key 失效。每 Inbox 最多 100 个未删除 key；容量满时可回收永久失效 key，管理 grant 撤销或可恢复的父暂停不会被当作回收理由。子 key 共用现有 HTTPS 发送端的 60 次/分钟入口限额；普通消息另受每 Source 30 条/分钟、10 条/2 秒约束。

可选 GitHub / Standard Webhooks 签名

generic 模式使用私有 URL bearer。对子 key 可显式选择 github 或 standard，并提供独立的私有验证 secret 文件。GitHub 按原始请求 body 验证 X-Hub-Signature-256，不签 delivery ID 或 timestamp；Standard Webhooks 绑定 delivery ID、timestamp 与原始 body，核对前后 300 秒时间窗。已配置模式必须拒绝缺失或错误签名；携带 header 不会自动启用模式，也不能触发降级。Standard Webhooks 是社区约定，不是统一 payload 格式。

ntfyx webhook create --name "GitHub events" --signature-mode github \
  --verification-secret-file ./github-webhook-secret.txt \
  --url-file ./private-github-url.txt --json

消息编码与重试

Topic 别名用作通知标题，最后一段用作消息正文。每一段按 UTF-8 百分号编码一次，包括空格、斜杠、#、? 和表情。消息支持 1–2,000 个字符，完整编码 URL 最多 8,192 个 UTF-8 字节。普通访问每次发送一条新通知；App 测试保留 Idempotency-Key 请求头，收到匹配消息前复用同一标识，避免响应不确定时重试重复发送。HEAD 和预取不会发送通知。

请保管好完整链接

链接包含仅发送 key，持有链接的人可以向绑定的 Topic 发通知。不要公开链接，也不要放进公开截图、共享日志或会抓取链接预览的服务。可在 App 管理或重新生成 key，使旧链接失效；该 key 不能读消息或管理收件箱。

进阶：继续支持 POST

已有 JSON POST 接入继续可用，原始 push token 仍通过 Authorization 请求头发送，并支持较长正文及可选 Session 字段。POST 的 push token 与简短 sk_ 发送 key 是独立凭据，请同时保管好。

curl -X POST 'https://api.ntfyx.me/v1/push/YOUR_INBOX_ID/YOUR_PUSH_ID' -H 'Authorization: Bearer YOUR_PUSH_KEY' -H 'Content-Type: application/json' -d '{"title":"Deployment","body":"Build ready"}'

进阶 POST 的会话分组

JSON POST 中可选的 session_id 与 session_name 可把同一任务的通知放进同一 Topic 下的 Session。一次任务使用稳定 ID。可选的随机 idempotency_key 可让相同内容重试返回原先已受理的事件；复用该 key 却改变内容会失败。HTTPS 发送通知；显式 JSON Call 请求可申请受支持的来电式提醒，但不提供提问、回复、读取消息或执行领取；需要验签回答时，使用 CLI 或 Agent 接入。

请求已受理，不等于手机已收到

accepted 只表示服务已受理，不证明手机已经收到或弹出系统提醒。App 测试会等待匹配消息进入收件箱。系统通知关闭时，消息仍可进入收件箱，但不会显示横幅。请分别检查通知权限、消息同步与网络状态。

推送 key 只有发送权限

它只能向配置的 Topic 发通知，与手机管理权限、接收解密密钥和 CLI Source 身份独立。可以在手机管理、停用或轮换 HTTPS 推送；轮换后旧 key 失效。服务不会把丢失的原始 key 返回给你，丢失时请轮换并更新自己的脚本。

从哪里开始加密

普通 CLI 与 Agent 消息的标题、正文、选项和回复在设备上端到端加密。明确的监控 / Webhook 管理固定授权问题及手机签名答案会披露给服务端核验。HTTPS 推送与 Webhook 请求在加密投递前对服务可见；可选供应商验证 secret 由服务加密存储，并在验签时以明文验证原始 body，是托管 secret，并非服务端不可见；My Monitor 会读取监控地址、规则和响应，公开发布者知道自己发送的内容。中继转发密文，仍处理标识符、时间、大小和推送令牌等运行元数据。不要在监控 URL 或请求示例中放密钥。尚未完成独立安全审计。

从首页完成第一次测试

按照 hello 案例完成测试，对照已受理与真正收到的状态。

实际案例：手机点击发送 hello

按使用场景开始

从 Agent 等你回答，到每周订阅和网站异常，选一个场景开始。看手机会收到什么，再按步骤接好。

查看全部案例

Webhook 可以来电式提醒或等待 Agent 回复吗？

手机主动开启后，JSON Webhook 可用 ntfyx.alert_mode="call" 请求来电式消息提醒。它只改变提醒请求，不扩大发送 key 的权限。Webhook 不能读消息或接收签名回答；需要确认、选项或文字时，使用 ntfyx ask 或本地 MCP。

普通消息与富消息

CLI 0.5.0 可独立发送普通文字、Markdown 和带指标／表格／图表的原生富消息，并在发送前本地校验。显示端版本与商店审核状态详见指南。

富消息格式与完整示例