Send change alerts from any site or app into one shared inbox
Integrate Nudge to Receive Notifications
Nudge is an open "notification inbox + subscription hub". Your site only needs to POST a small JSON payload to one HTTP endpoint whenever something happens, and your users will receive the alert in their own Nudge inbox — together with alerts from every other site they follow. No message queue, no email service, no push infrastructure to build.
Integration takes three steps, about 10 minutes. No SDK required — any backend language works.
Overview
Get credentials
Create a "project" for your site and get a dedicated token.
Push events
POST a JSON payload to /api/ingest.php when something changes.
Users subscribe
Add a deep-link button; after sign-in users are auto-subscribed and see a welcome card.
Step 1 · Get a project & token
Each publisher maps to a "project" with a unique slug, display name and token. The token is the only credential for pushing events — keep it server-side, never in front-end code or a public repo.
php bin/create_project.php your-app "Your App Name"
# prints: slug / name / token / ingest endpoint
Step 2 · Push events to ingest
Whenever something "worth knowing" happens on your site, send a JSON request to the ingest endpoint. It is stateless: Nudge handles storage, deduplication, rate limiting, and delivery into each subscriber's inbox.
https://nudgealert.com/api/ingest.phpPOST · Content-Type: application/jsonMinimal request
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."}'
Request with all fields
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"
}'
Fields & responses
| Field | Required | Description |
|---|---|---|
token | yes | Project credential, keep server-side |
title | no | Alert title; defaults to (no title) |
body | no | Body text, newlines allowed |
topic | no | Group (e.g. quota-change); defaults to default; users may subscribe per topic |
level | no | info / warning / high / critical; defaults to info |
dedup_key | no | Dedup key: repeated values under one project are stored once, returning duplicated |
Responses
| Event stored | { "ok": true, "id": 12 } |
| Deduplicated | { "ok": true, "duplicated": true } |
Error codes
400 | invalid_json | Body is not valid JSON |
401 | missing_token | No token provided |
403 | invalid_token | Invalid token |
429 | rate_limited | Over 60 events/min per project |
500 | db_error | Server-side write failure |
Code examples
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}
Step 3 · One-click subscribe
Put a deep link behind your "Subscribe to alerts" button. When a user opens Nudge and signs in with their email, they are automatically subscribed to your project and see a landing welcome card explaining that future alerts will land in this inbox.
https://nudgealert.com/?sub=<slug>&from=<source>| Param | Description |
|---|---|
sub | Your project slug (required) — decides which project to auto-subscribe |
from | Source id (optional) — used for the welcome card; known sources get a friendly name + back link |
Drop it into a button / email
<a class="btn" href="https://nudgealert.com/?sub=your-app&from=your-site"
target="_blank" rel="noopener">
Subscribe to quota alerts
</a>
Best practices
- Push only on change — Nudge is for change alerts, not status polling. POST only when quota, price or status actually changes.
- Use dedup_key — Derive a stable key from "object + change" (e.g. groq:rpm:20to10) so cron reruns never spam users.
- Pick the right level — info for normal, warning to watch, high for important, critical for urgent — users triage at a glance.
- Group by topic — Split event types into topics so users can subscribe only to what they care about.
- Protect the token — Keep the token in server env/config only; if leaked, ask the admin to rotate it immediately.
- Server-side calls — Always push from your backend — never expose the token to browsers or clients.
FAQ
Do I need an SDK or an account?
No. Publishers only need a token and one HTTP POST; subscribers just sign in to Nudge with an email, no password.
Are events sent to everyone?
Only to users subscribed to your project (and matching topic). Others cannot see them.
Is there a rate limit?
Yes, 60 events per minute per project (429 rate_limited). Batch or stagger large bursts.
Can events be forwarded to my webhook?
Yes. Users can set a forward webhook on subscription; Nudge relays to WeCom / Slack / Telegram / custom endpoints.
Is delivery real-time?
Events are visible in the inbox immediately. Browser/email push depends on user-side config and upcoming features.
Ready to integrate?
Send your site info to the admin for a token, copy one example, change two lines — and your first alert is in Nudge.
Open Nudge inbox →