Build a hejj widget, step by step

Data gets to the tile in one of two ways, and you choose per view:

  Your app                         hejj                         The user
  ────────                         ────                         ────────
  1. host a manifest ───────────►  reads it
  2. "Add to hejj" / device code ► consent page ─────────────►  clicks Allow
     ◄──────────── token + signing secret + grant_id
  3a. push blocks ───────────────► stores them ──────────────►  tile updates
  3b. ◄──────── signed GET (pull) ─ tile on screen
      answer with blocks ────────►                    ───────►  tile updates

1. 1

   Ask hejj for a connect code

   Send your manifest and the widget you want. This one has a single push view called main:

   {
     "hejj": 1,
     "name": "My first widget",
     "widgets": {
       "hello": {
         "title": "Hello",
         "endpoints": [{ "id": "main", "title": "Main", "mode": "push" }]
       }
     }
   }

   curl -X POST https://hejj.net/api/apps/v1/device \
     -H 'content-type: application/json' \
     -d '{"widget":"hello","manifest":{"hejj":1,"name":"My first widget",
          "widgets":{"hello":{"title":"Hello",
          "endpoints":[{"id":"main","title":"Main","mode":"push"}]}}}}'

   {
     "device_code": "Zx8…",
     "user_code": "WDJB-MJHT",
     "verification_uri": "https://hejj.net/link",
     "verification_uri_complete": "https://hejj.net/link?code=WDJB-MJHT",
     "interval": 5,
     "expires_in": 600
   }

2. 2

   Approve it in hejj

   Open verification_uri_complete in a browser where you're signed in to hejj (or open /link and type the user_code). Check the consent page and click Allow. The code is valid for 10 minutes.

3. 3

   Collect your token

   Exchange the device_code for a token. Before you click Allow this answers authorization_pending; afterwards you get the token, once.

   curl -X POST https://hejj.net/api/apps/v1/token \
     -H 'content-type: application/json' \
     -d '{"grant_type":"urn:ietf:params:oauth:grant-type:device_code",
          "device_code":"<device_code from step 1>"}'

   {
     "access_token": "hejj_wt_…",
     "token_type": "Bearer",
     "signing_secret": "hejj_ws_…",
     "grant_id": "gr_…",
     "widget": "hello",
     "endpoints": [{ "id": "main", "mode": "push" }],
     "context": []
   }

4. 4

   Send your first data

   curl -X POST https://hejj.net/api/apps/v1/push/main \
     -H 'authorization: Bearer hejj_wt_…' \
     -H 'content-type: application/json' \
     -d '{"v":1,"blocks":[
           {"type":"metric","label":"Coffees today","value":3,"unit":"count"},
           {"type":"status","state":"ok","label":"All good"}]}'

   A 200 means it's stored. A 422 lists exactly what to fix.

5. 5

   Put it on your board

   In hejj, open Add ▸ Widget. Your widget is under Connected apps. Add it, then run step 4 again with a different value and watch the tile change.

1. 1

   Write your manifest and host it

   Put a JSON file at a stable https URL, for example https://acme.example/hejj.json. That exact URL is your client_id. It must answer 200 directly (no redirects).

   {
     "hejj": 1,
     "name": "Acme Finance",
     "icon": "https://acme.example/icon.png",
     "homepage": "https://acme.example",
     "redirect_uris": ["https://acme.example/hejj/callback"],
     "actions_url": "https://api.acme.example/hejj/actions",
     "widgets": {
       "balance": {
         "title": "Acme balance",
         "description": "Your accounts at a glance",
         "size": {
           "default": { "w": 6, "h": 8 },
           "min": { "w": 3, "h": 4 },
           "max": { "w": 12, "h": 16 }
         },
         "endpoints": [
           { "id": "total", "title": "Balance", "mode": "pull",
             "url": "https://api.acme.example/hejj/total", "ttl": 300,
             "actions": ["refresh"] },
           { "id": "alerts", "title": "Alerts", "mode": "push" }
         ]
       }
     }
   }

   Every URL hejj calls (icon, actions_url, pull url) must be https on the manifest's domain or a subdomain of it. All the rules are in the manifest reference.

2. 2

   Check it in the playground

   Paste the manifest into the playground. It lists every problem with its path, and previews your blocks in every theme.

3. 3

   Add the button

   The button is just a link to hejj's consent page. Make a fresh PKCE pair and a random state for each click, and keep them in the user's session:

   import { createHash, randomBytes } from "node:crypto";
   
   const HEJJ = "https://hejj.net";
   const CLIENT_ID = "https://acme.example/hejj.json";
   const REDIRECT_URI = "https://acme.example/hejj/callback";
   
   // When the user clicks "Add to hejj":
   export function addToHejjUrl(session) {
     const verifier = randomBytes(32).toString("base64url");
     const challenge = createHash("sha256").update(verifier).digest("base64url");
     const state = randomBytes(16).toString("base64url");
     session.hejj = { verifier, state }; // remember both for the callback
   
     const url = new URL("/connect/app", HEJJ);
     url.search = new URLSearchParams({
       response_type: "code",
       client_id: CLIENT_ID,
       widget: "balance",
       redirect_uri: REDIRECT_URI,
       state,
       code_challenge: challenge,
       code_challenge_method: "S256",
     }).toString();
     return url.toString(); // redirect the browser here
   }

4. 4

   Handle the callback

   After Allow, hejj sends the browser to your redirect_uri with ?code=…&state=…. After Cancel you get ?error=access_denied. Check state, then exchange the code from your server within 60 seconds:

   // GET /hejj/callback?code=…&state=…  (or ?error=access_denied&state=…)
   export async function hejjCallback(query, session, currentUser) {
     const saved = session.hejj;
     delete session.hejj;
     if (!saved || query.state !== saved.state) throw new Error("state mismatch");
     if (query.error) return "cancelled"; // the user clicked Cancel
   
     const res = await fetch("https://hejj.net/api/apps/v1/token", {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({
         grant_type: "authorization_code",
         code: query.code,
         code_verifier: saved.verifier,
         client_id: CLIENT_ID,
         redirect_uri: REDIRECT_URI,
       }),
     });
     if (!res.ok) throw new Error(`hejj token: ${res.status} ${await res.text()}`);
     const t = await res.json();
   
     // Store against YOUR user, encrypted at rest.
     await db.hejjGrants.upsert({
       userId: currentUser.id,
       grantId: t.grant_id,
       accessToken: t.access_token,
       signingSecret: t.signing_secret,
     });
     return "connected";
   }

   Store the connection against your own user

   hejj never tells you who the user is. The state you created in step 3 is how you know which of your users just connected.
5. 5

   Send data

   For push views, call the push endpoint with the access token. For pull views, serve your URL and check the signature.

6. 6

   Handle disconnects

   If a push returns 401, the user disconnected you in hejj. Delete the stored connection and show your button again.

1. 1

   Create a device secret

   Generate a random secret, keep it on your server, and put its SHA-256 hash in your manifest as device_secret_sha256. Without it, hosted device flows are off.

   openssl rand -hex 32                      # your secret: store it as HEJJ_DEVICE_SECRET
   printf %s "$HEJJ_DEVICE_SECRET" | shasum -a 256   # put this hash in the manifest

2. 2

   Start the flow and show the code

   Call /api/apps/v1/device with your manifest URL and secret. Print “Open {verification_uri} and enter {user_code}”, then poll the token endpoint every interval seconds:

   const HEJJ = "https://hejj.net";
   
   const start = await fetch(`${HEJJ}/api/apps/v1/device`, {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({
       client_id: "https://acme.example/hejj.json",
       client_secret: process.env.HEJJ_DEVICE_SECRET,
       widget: "balance",
     }),
   }).then((r) => r.json());
   
   console.log(`Open ${start.verification_uri} and enter ${start.user_code}`);
   
   let interval = start.interval;
   for (;;) {
     await new Promise((r) => setTimeout(r, interval * 1000));
     const res = await fetch(`${HEJJ}/api/apps/v1/token`, {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify({
         grant_type: "urn:ietf:params:oauth:grant-type:device_code",
         device_code: start.device_code,
       }),
     });
     const body = await res.json();
     if (res.ok) { save(body); break; }            // access_token, signing_secret, grant_id
     if (body.error === "authorization_pending") continue;
     if (body.error === "slow_down") { interval += 5; continue; }
     throw new Error(body.error);                  // access_denied or expired_token
   }

   Poll answer	What to do
   authorization_pending	Not approved yet. Keep polling.
   slow_down	You polled too fast. Wait longer between polls.
   access_denied	The user clicked Cancel. Stop.
   expired_token	10 minutes passed. Start again.
   200 + token	Done. Save it. Polling again gives invalid_grant.

3. 3

   Send data

   Same as every other app: push when something changes.

{
  "v": 1,
  "blocks": [ … 1 to 12 blocks … ],
  "href": "https://acme.example/accounts",   // optional: makes the tile title a link
  "ttl": 120,                                // optional (pull): fetch again sooner
  "updated_at": "2026-10-12T08:00:00Z"       // optional
}

Push: you send, whenever data changes

curl -X POST https://hejj.net/api/apps/v1/push/alerts \
  -H 'authorization: Bearer hejj_wt_…' \
  -H 'content-type: application/json' \
  -d '{"v":1,"blocks":[{"type":"status","state":"warn","label":"Card expires soon"}]}'

• The last part of the URL is the view's id, and it must be a push view.
• Each push replaces that view's data. Open tabs update in about a second.
• Push when data changes, not on a timer. You get 60 pushes a minute and 1 000 a day per connection.

Pull: hejj asks, while the tile is on screen

hejj calls your view's url from its server, at most once per ttl (default 5 minutes). It adds grant to the query, and tz / locale only if the user ticked those boxes:

GET https://api.acme.example/hejj/total?grant=gr_…&tz=Europe%2FStockholm
Hejj-Signature: t=1760000000,v1=<hex>
Hejj-Grant: gr_…
User-Agent: hejjBot/1.0 (+https://hejj.net/bot)

import express from "express";
import { verifyHejj } from "./verify-hejj.js"; // see "Checking signatures"

const app = express();
app.get("/hejj/total", async (req, res) => {
  const grant = await db.hejjGrants.findByGrantId(req.query.grant);
  if (!grant) return res.status(404).end(); // tile shows "Reconnect"
  if (!verifyHejj(req, "", grant.signingSecret)) return res.status(401).end();

  const balance = await getBalance(grant.userId);
  res.json({
    v: 1,
    href: "https://acme.example/accounts",
    blocks: [
      { type: "metric", label: "Balance", value: balance, unit: "money", currency: "SEK" },
      { type: "actions", buttons: [{ id: "refresh", label: "Refresh" }] },
    ],
  });
});

Checking hejj's signature

Every pull and button request is signed with the connection's signing_secret. Check it, so nobody else can ask for your users' data:

1. Read t=… and every v1=… from the Hejj-Signature header.
2. Reject if the time is more than 5 minutes from now.
3. Build <t>.<METHOD>.<path and query as received>.<sha256 hex of the raw body>. For GET, hash the empty string.
4. HMAC-SHA256 it with the signing secret, as hex.
5. Accept if any v1 matches (use a constant-time compare).

// Node 18+ (no dependencies)
import { createHash, createHmac, timingSafeEqual } from "node:crypto";

export function verifyHejj(req, rawBody, secret) {
  const h = req.headers["hejj-signature"] ?? "";
  const t = Number(/(?:^|,)t=(\d+)/.exec(h)?.[1]);
  const sigs = [...h.matchAll(/v1=([0-9a-f]{64})/g)].map((m) => m[1]);
  if (!t || !sigs.length || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const bodyHash = createHash("sha256").update(rawBody ?? "").digest("hex");
  const expected = createHmac("sha256", secret)
    .update(`${t}.${req.method}.${req.originalUrl ?? req.url}.${bodyHash}`)
    .digest("hex");
  return sigs.some((s) => timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
}

# Python 3
import hashlib, hmac, re, time

def verify_hejj(method, path_and_query, raw_body: bytes, header: str, secret: str) -> bool:
    t = re.search(r"(?:^|,)t=(\d+)", header or "")
    sigs = re.findall(r"v1=([0-9a-f]{64})", header or "")
    if not t or not sigs or abs(time.time() - int(t.group(1))) > 300:
        return False
    canonical = f"{t.group(1)}.{method}.{path_and_query}.{hashlib.sha256(raw_body).hexdigest()}"
    expected = hmac.new(secret.encode(), canonical.encode(), hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(s, expected) for s in sigs)

Buttons

Add an actions block with up to 3 buttons. Each button's id must be listed in that view's actions in the manifest, and the manifest needs an actions_url. When the user taps one, hejj POSTs to it, signed:

{ "type": "actions", "buttons": [
  { "id": "mark-paid", "label": "Mark paid", "style": "primary",
    "confirm": "Mark invoice 1042 as paid?", "value": "inv_1042" }
] }

POST https://api.acme.example/hejj/actions
Hejj-Signature: t=…,v1=…
content-type: application/json

{"grant_id":"gr_…","endpoint":"total","action":"mark-paid","button_value":"inv_1042"}

app.post("/hejj/actions", express.raw({ type: "*/*" }), async (req, res) => {
  const msg = JSON.parse(req.body.toString("utf8"));
  const grant = await db.hejjGrants.findByGrantId(msg.grant_id);
  if (!grant || !verifyHejj(req, req.body, grant.signingSecret)) return res.status(401).end();

  if (msg.action === "mark-paid") {
    await markPaid(grant.userId, msg.button_value); // the value YOU put on the button
    return res.json({ toast: "Marked as paid" });
  }
  if (msg.action === "refresh") return res.json(await buildEnvelope(grant)); // new blocks
  res.status(204).end();
});

Answer within 5 seconds with a new envelope (shown at once), {"toast":"…"} (a short message, up to 140 characters), or 204. button_value is always the value you sent: the browser can't change it. Buttons not listed in the view's manifest actions (or without an actions_url) are hidden, so push-only apps can't show buttons.

{
  "v": 1,
  "blocks": [
    { "type": "metric", "label": "Balance", "value": 12480.5, "unit": "money",
      "currency": "SEK", "delta": { "value": 320, "period": "this week", "good": "up" } },
    { "type": "sparkline", "values": [11900, 12010, 12160, 12480.5], "color": "green" },
    { "type": "list", "items": [
      { "title": "Rent", "value": "−9 200", "emoji": "🏠", "time": "2026-10-01T08:00:00Z" }
    ] }
  ]
}

• Money is in whole units (1234.5), not cents. hejj formats numbers for the user's language.
• Colors are names: stone red orange amber yellow lime green teal cyan blue indigo violet purple pink rose. Never hex.
• Times are ISO 8601 with a zone (Z or +02:00). hejj shows “5 min ago”.
• Links are http(s) only and open in a new tab.

See every block rendered in the block catalog, and every field with its limits in the spec (§8).

Machine-readable: manifest JSON Schema.

{ "client_id": "https://acme.example/hejj.json", "client_secret": "…", "widget": "balance" }
// or, without a website:
{ "manifest": { …inline manifest… }, "widget": "hello" }

{ "grant_type": "authorization_code", "code": "…", "code_verifier": "…",
  "client_id": "https://acme.example/hejj.json",
  "redirect_uri": "https://acme.example/hejj/callback" }

{ "grant_type": "urn:ietf:params:oauth:grant-type:device_code", "device_code": "…" }

Calls hejj makes to you

Both carry Hejj-Signature: check it. The full machine-readable API is the OpenAPI file.

• Store access_token and signing_secret encrypted, next to your own user id and the grant_id.
• Users can disconnect you any time in hejj's Settings ▸ Connected apps. Your next push gets 401, and pull or button requests stop.
• If a secret leaks, rotate it.
• hejj never sends you the user's name, email, account, IP address, or anything else on their boards. Time zone and language arrive only if they tick the box.

• The manifest URL answers 200 with valid JSON (check it in the playground).
• Connecting stores grant_id, access_token and signing_secret against your own user.
• Pull and button endpoints check Hejj-Signature (tested with the example above).
• One real payload passes in the playground.
• A 401 from hejj deletes the connection on your side.
• You push when data changes, not on a timer.