把任何站点 / 应用的变动提醒,送进一个统一收件箱
如何接入 Nudge 接收通知
Nudge 是一个开放的「通知接收 + 订阅中台」。你的站点只需要在事件发生时向一个 HTTP 接口 POST 一条 JSON,用户就能在自己的 Nudge 收件箱里收到提醒,并与来自其他站点的提醒汇聚在一处。无需自建消息队列、邮件服务或 App 推送。
整个接入只有三步,约 10 分钟,不需要 SDK,任意后端语言都能用。
三步概览
拿到凭证
为你的站点创建一个「项目」,获得专属 token。
推送事件
事件发生时,POST 一条 JSON 到 /api/ingest.php。
用户订阅
放一个深链按钮,用户登录后自动订阅并看到欢迎提示。
第一步 · 拿到项目与 token
每个接入方对应一个「项目」(project),有唯一的 slug、展示名和 token。token 是推送事件的唯一凭证,务必只放在服务端,不要写进前端代码或公开仓库。
php bin/create_project.php your-app "Your App Name"
# 输出:slug / name / token / ingest endpoint
第二步 · 推送事件到 ingest
当你的站点出现「值得让用户知道」的变化时,向 ingest 端点发送一个 JSON 请求。它是无状态的,Nudge 负责入库、去重、限频,并按用户订阅把事件投递到各人收件箱。
https://nudgealert.com/api/ingest.phpPOST · Content-Type: application/json最小可用请求
curl -X POST https://nudgealert.com/api/ingest.php \
-H "Content-Type: application/json" \
-d '{"token":"YOUR_TOKEN","title":"New free tier available","body":"Groq raised its free RPM to 30."}'
带全部字段的请求
curl -X POST https://nudgealert.com/api/ingest.php \
-H "Content-Type: application/json" \
-d '{
"token": "YOUR_TOKEN",
"topic": "quota-change",
"title": "Groq free quota changed",
"body": "RPM 20 -> 10, effective today.",
"level": "high",
"dedup_key": "groq:rpm:20to10:2026-11-14"
}'
请求字段与响应
| 字段 | 必填 | 说明 |
|---|---|---|
token | 是 | 项目凭证,服务端保存 |
title | 否 | 提醒标题;缺省为 (no title) |
body | 否 | 正文,支持换行 |
topic | 否 | 主题分组(如 quota-change);缺省 default,用户可按主题订阅 |
level | 否 | info / warning / high / critical,缺省 info |
dedup_key | 否 | 去重键:同一项目下重复值只入库一次,返回 duplicated |
响应
| 新事件入库 | { "ok": true, "id": 12 } |
| 命中去重 | { "ok": true, "duplicated": true } |
错误码
400 | invalid_json | 请求体不是合法 JSON |
401 | missing_token | 未提供 token |
403 | invalid_token | token 无效 |
429 | rate_limited | 超过每项目 60 条/分钟 |
500 | db_error | 服务端写入失败 |
代码示例
PHP
<?php
$payload = [
"token" => getenv("NUDGE_TOKEN"),
"topic" => "quota-change",
"title" => "Groq free quota changed",
"body" => "RPM 20 -> 10",
"level" => "high",
"dedup_key" => "groq:rpm:20to10:2026-11-14",
];
$ch = curl_init("https://nudgealert.com/api/ingest.php");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ["Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);
// $res => ["ok" => true, "id" => 12] or ["ok" => true, "duplicated" => true]
Node.js / fetch
const res = await fetch("https://nudgealert.com/api/ingest.php", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
token: process.env.NUDGE_TOKEN,
topic: "quota-change",
title: "Groq free quota changed",
body: "RPM 20 -> 10",
level: "high",
dedup_key: "groq:rpm:20to10:2026-11-14",
}),
});
const data = await res.json();
// data => { ok: true, id: 12 } or { ok: true, duplicated: true }
Python
import os, json, urllib.request
payload = {
"token": os.environ["NUDGE_TOKEN"],
"topic": "quota-change",
"title": "Groq free quota changed",
"body": "RPM 20 -> 10",
"level": "high",
"dedup_key": "groq:rpm:20to10:2026-11-14",
}
req = urllib.request.Request(
"https://nudgealert.com/api/ingest.php",
data=json.dumps(payload).encode(),
headers={"Content-Type": "application/json"},
method="POST",
)
with urllib.request.urlopen(req) as r:
data = json.load(r) # {"ok": true, "id": 12}
第三步 · 让用户一键订阅
在「订阅提醒」按钮里放一个深链。用户点开 Nudge、用邮箱登录后,会自动订阅对应项目,并看到一张说明「订阅成功、以后提醒会进这个收件箱」的落地欢迎卡片。
https://nudgealert.com/?sub=<slug>&from=<source>| 参数 | 说明 |
|---|---|
sub | 你的项目 slug(必填),决定自动订阅哪个项目 |
from | 来源标识(可选),用于欢迎卡片的来源文案;已知来源显示友好名与返回链接 |
可直接放进按钮 / 邮件
<a class="btn" href="https://nudgealert.com/?sub=your-app&from=your-site"
target="_blank" rel="noopener">
Subscribe to quota alerts
</a>
最佳实践
- 只在变化时推送 — Nudge 是「变动提醒」而非状态轮询。只在额度、价格、状态真的变化时才 POST,避免打扰。
- 善用 dedup_key — 用「对象 + 变化」生成稳定键(如 groq:rpm:20to10),cron 重复跑也不会刷屏。
- 选对 level — info 普通动态、warning 需留意、high 重要、critical 紧急,用户一眼分辨优先级。
- 按 topic 分类 — 把不同类型事件分到不同 topic,用户可只订阅关心的主题。
- 保护 token — token 只存服务端环境变量 / 配置;如泄露请立即联系管理员重置。
- 服务端调用 — 永远从后端推送,不要暴露 token 到浏览器或客户端。
常见问题
需要 SDK 或注册账号吗?
不需要。发布方只需一个 token 和一次 HTTP POST;订阅方用户用邮箱登录 Nudge 即可,无需密码。
事件会发给所有用户吗?
只发给订阅了你项目(及对应 topic)的用户,别人看不到。
推送有频率限制吗?
有,每个项目每分钟最多 60 条(429 rate_limited)。批量事件建议合并或错峰。
能转发到自己的 Webhook 吗?
可以。用户在订阅时可填写转发 Webhook,Nudge 会把事件再分发到企业微信 / Slack / Telegram / 自定义端点。
是实时推送吗?
事件入库即对用户可见(收件箱)。浏览器通知 / 邮件等渠道取决于用户侧配置与后续能力开放。
准备好接入了吗?
把你的站点信息发给管理员拿到 token,复制上面的示例改两行,就能把第一条提醒送进 Nudge。
打开 Nudge 收件箱 →