Skip to content
notific.menotific.menotific.me

How it works

notific.me has five core pieces. Everything else is built on top of them.

Piece What it is Example
Event Something happened deploy.ok, lead.new, container.die
Policy Who should know, when, how urgently and at which level “Everything from AI agents needs level 2”
Card How the notification looks Summary, declarative card
Action What can be done from it Approve, pick an option, open a dashboard
Reply The signed answer that goes back { question_set_id, version, answers, signature }

The whole cycle

Section titled “The whole cycle”
How notific.me works, end to endYour system sends an event or a question. The ingest API validates it, the policy rules decide whether and to whom it is delivered, the notification with its card reaches the person in the app, the person decides and signs, the server accepts the decision exactly once and sends the signed reply back to your system by webhook or long-poll.Your systemSDK · REST · hookAI agent (MCP)Ingest APIvalidates, dedups,idempotencyPolicy rulesnotify · digestsuppress · escalateNotificationsummary + card+ questionsPersonapp · PWA · pushSigned decisionlevel 0–4: biometricsor 2FA codeAtomic acceptone reply wins+ outboxReply backsigned webhookor ask long-polldeliversigned reply
  1. Your system sends an event (POST /v0/events) or a question set (POST /v0/asks) with a service token. It can also post any webhook to an incoming hook, or an AI agent can use the MCP server.
  2. The ingest API validates the payload against the open protocol, merges duplicates by dedup_key, and makes retries safe with idempotency keys.
  3. The policy rules of the workspace decide what happens: notify, digest, suppress or escalate.
  4. A notification is created for each recipient, carrying a summary, a card and, for questions, the question set.
  5. The person receives it on the app, the web app or a push notification.
  6. The person decides. The level defines what that takes: a tap, an unlocked device, biometrics or a 2FA code, and possibly a quorum.
  7. The server accepts the answer atomically: one answer wins, and the reply plus the webhook to your system are saved in the same transaction (transactional outbox), so a decision is never lost.
  8. The signed reply goes back to your system: as a webhook to callback_url, signed with Ed25519, or as the result of the ask() call that is long-polling.

Policy rules

Section titled “Policy rules”
How policy rules decideAn event is checked against the workspace rules in order; the first rule that matches decides the action: notify now, digest (grouped summary), suppress (stored but not delivered) or escalate (notify with high priority and extra recipients). During quiet hours a notify becomes a digest unless the rule bypasses quiet hours.Eventsource · typeseverity · timeRules, in orderfirst match wins;else the defaultQuiet hours?notify → digestunless bypass_quietnotifydelivered nowdigestgrouped in a summarysuppressstored, not deliveredescalatehigh priority + extra people

Rules are checked in order, and the first one that matches decides. When none matches, the workspace default applies. Quiet hours can turn notify into a digest (or suppress it) below a minimum severity. Learn more in Rules and policies.

The life of a question

Section titled “The life of a question”
Life of a question setPOST /v0/asks creates the question set in the open state. Your code waits with GET /v0/asks/{id}?wait=60 (long-poll) or receives a webhook. It ends answered (signed reply), timeout (on_timeout answers applied, reply included), expired or cancelled (no reply).POST /v0/asks201 · Idempotency-KeyopenGET /v0/asks/{id}?wait=60or callback_urlansweredsigned replytimeouton_timeout answers appliedexpired · cancelledno reply (AskClosedError)

ask() in the SDK does both steps for you: it creates the question set and long-polls until it is answered or times out. See Questions and answers.

Decision levels

Section titled “Decision levels”
Decision levels 0 to 4The service asks for a minimum level; the workspace can only raise it. The highest level among the questions applies. Level 0 is a tap, level 1 an unlocked device, level 2 biometrics or a 2FA code (a 2FA session window may cover it), level 3 biometrics or a 2FA code for every action, online and with a short expiry, level 4 is level 3 plus a quorum of people.Service levellevel: 0–4 in ask()(default 1)Workspace minimumcan raise,never lowerEffective levelhighest amongthe questions0 · tapmark as read, view1 · unlocked devicerestart a container2 · biometrics or 2FA2FA window may cover it3 · biometrics or 2FA, every actiononline · short expiry4 · level 3 + quorume.g. 2 of 3 approve (app)

The service sets the minimum level in ask(). The workspace can raise it, never lower it. The highest level among the questions applies to the whole set, and one signature covers all the answers.

Signing with the 2FA code

Section titled “Signing with the 2FA code”

Not every device has a fingerprint reader, and the browser has no biometrics. A person who enables two-step verification (an authenticator app with TOTP codes) can sign level 2 and 3 decisions with the 6-digit code.

Signing a decision with the 2FA codeWithout biometrics, a person with 2FA enabled can sign level 2 and 3 decisions with the 6-digit code of an authenticator app. Level 3 always asks for a code. For level 2, if the session is inside the 2FA window the person chose, it is signed without typing a code; otherwise the code is typed, checked by the server (±30 seconds, single use, 5 wrong codes in 15 minutes lock), and a valid code opens the window for that session.Open the decisionno biometrics here(browser, PWA)Level?2 or 3Type the 6-digit codefrom the authenticator appServer checks±30 s · single use5 wrong / 15 min = lock2FA window open?this session,0–240 min you chooseReply acceptedauth_method: "totp"(valid code opens the window)Signed without a codelevel 2 onlylevel 3validlevel 2noyes
  • Level 3 always asks for a new code, for every action.
  • Level 2 can use a 2FA window the person chooses in their account (off, 5, 15, 30, 60, 120 or 240 minutes). After a valid code, that session can sign level 2 decisions without typing the code again. With 50 pending approvals, nobody wants to type 50 codes.
  • Biometrics is always one prompt per decision.
  • Level 4 (quorum) still requires the app with biometrics.

Delivery

Section titled “Delivery”
How a notification reaches the personWhen the app is open, notifications arrive through the WebSocket gateway in milliseconds. When it is closed, the push relay sends a push through APNs (iOS), FCM (Android) or Web Push for the installed PWA, encrypted end to end. When the app opens again it syncs incrementally from a cursor.Notificationfor each recipientApp open?WebSocket gatewaytens of millisecondsPush relayusually 1–2 s,no guaranteeInbox updates liveapp · web · PWAAPNsiOS appFCMAndroid appWeb PushPWA · VAPID · encryptedOn open: sync from cursoryesno
  • App open: the WebSocket gateway delivers in tens of milliseconds.
  • App closed: the push relay sends through APNs (iOS), FCM (Android) or Web Push for the installed PWA. Web Push is encrypted end to end, so it can show the title and summary.
  • When the app opens again, it syncs incrementally from a cursor, so nothing is missed.

See App, PWA and push.