Widget System Documentation

What it is

A signed iframe endpoint at /widget for embedding small server-rendered widgets (charts, metrics, notes, lists) inside posts.

How to use it in a post

Just paste a URL. The site signs and embeds it for you automatically.

Bare URL on its own line

https://adam.holter.com/widget?type=metric&label=Active%20Users&value=12,438&sub=last%2024h

That URL on its own paragraph renders as an iframe. You don’t need to sign it. The server signs it at render time before sending HTML to the browser.

Relative URL

/widget?type=note&title=Heads%20up&text=Posted%20automatically%20from%20Apify.

Relative URLs work too, which is convenient for pipelines that don’t know the canonical host.

Shortcode (optional, for custom height)

[holter_widget url="/widget?type=chart&kind=bar&labels=A|B|C&values=10|20|30" height="360"]

Widget types

metric

Params: label, value, sub (optional), color (optional hex).

chart

Params: kind (bar, line, pie, doughnut), title, labels (pipe-delimited), values (pipe-delimited numbers), series (optional dataset label).

note

Params: title, text.

list

Params: title, items (pipe-delimited).

Security model

Every /widget request requires a valid HMAC-SHA256 sig derived from the params and a server-side secret. Without a valid signature, the endpoint returns 403.
The secret never leaves the server. Auto-signing happens inside the_content, so URLs in trusted post content get signed; URLs constructed externally cannot be forged.
The endpoint requires same-origin Referer for embedded loads and sets X-Frame-Options: SAMEORIGIN, so widgets only embed on adam.holter.com.
Rendered output never echoes raw HTML or JS from the URL. The type param selects a server-side template; data params are typed and sanitized.

Pipeline notes

Posts published via Apify or any other pipeline only need to emit a paragraph containing a /widget?... URL. No signing step is required upstream. The site handles signing, sandboxing, and embedding on every render.

Manual signer

For URLs you want to use outside post content (e.g. in a Customizer block, an email, an external dashboard), the admin signer at /widget-sign returns a pre-signed URL. Most authors will never need it.