Nudge
Powered by Nudge · open notification hub
← Back to inbox

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

1

Get credentials

Create a "project" for your site and get a dedicated token.

2

Push events

POST a JSON payload to /api/ingest.php when something changes.

3

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.

Access is currently invite-based: send your site name, slug (e.g. your-app) and a short description to the Nudge admin to get a token. If you self-host Nudge, use the CLI shipped with the project:
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.

Endpointhttps://nudgealert.com/api/ingest.php
Method / Content-TypePOST  ·  Content-Type: application/json

Minimal 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

FieldRequiredDescription
tokenyesProject credential, keep server-side
titlenoAlert title; defaults to (no title)
bodynoBody text, newlines allowed
topicnoGroup (e.g. quota-change); defaults to default; users may subscribe per topic
levelnoinfo / warning / high / critical; defaults to info
dedup_keynoDedup 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

400invalid_jsonBody is not valid JSON
401missing_tokenNo token provided
403invalid_tokenInvalid token
429rate_limitedOver 60 events/min per project
500db_errorServer-side write failure

Code examples

Replace YOUR_TOKEN with your project token. All examples must run server-side only.

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.

Deep link formathttps://nudgealert.com/?sub=<slug>&from=<source>
ParamDescription
subYour project slug (required) — decides which project to auto-subscribe
fromSource 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>
Replace your-app with your slug and your-site with your source id.

Best practices

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 →