Protocol
Versioning
This page lists what we promise about a payload that you write today. It also lists the things that Apple controls.
Two numbers
Every payload states its protocol version, as "v": 1. Every
request from the app contains two numbers. v is the version that the app
supports. rev is the revision of that version that the app
supports. A new version is for a change that breaks existing payloads. A new revision is for
an addition that does not break existing payloads.
What we promise
A payload that works keeps working
A version-1 payload that renders correctly today continues to render the same way. It has the same nodes, the same fields and the same colours, and the same layout rules apply. Within a version, we do not change the meaning of an existing field. We do not rename a field, make an optional field required, or change a default.
The layout rules are part of the version
The rules on the Layout page say how a stack divides its space, what fills, what stretches, and how text wraps and truncates. These rules are fixed for the life of version 1. The one exception is a bug. If the app or the preview on this site does something that the written rules do not say, we fix it to match the rules. We list the fix in the changelog below. The rules change only in a new version.
New features are additions
New node types, new fields and new values arrive as revisions of version 1. Each revision is listed below with what it added. A revision does not change how an older payload renders.
If an app does not know a feature, the app refuses a payload that uses the feature. The app
reports a clear error, and the last good payload stays on screen. People update the app at
different times, so every request contains rev. Send a newer node only if
rev is at least the revision that added the node. Otherwise, send a node that
every app understands.
// Suppose revision 2 adds a "chart" node. rev arrives with every request.
app.get("/widget", (request, response) => {
const rev = Number(request.query.rev ?? 1);
const trend = rev >= 2
? { type: "chart", values: week } // only apps that know revision 2
: { type: "gauge", value: week.at(-1), max: 100 }; // understood by every v1 app
response.json({ v: 1, view: { type: "vstack", children: [title, trend] } });
});
An older app ignores a field that it does not know. A payload can therefore contain a new
optional field for newer apps, and you do not need to branch on rev.
The changelog says which additions are optional fields.
A breaking change gets a new version, and the old version keeps working
If a change would alter existing payloads, the change goes into version 2. To use version
2, write "v": 2. Nothing changes for payloads that say "v": 1.
After version 2 exists, the app renders version 1 for at least two years. We announce the
end of support on this page at least six months before it happens.
Deprecation before removal
Before we remove a feature, we mark it as deprecated in the reference and say what to use instead. A deprecated feature keeps working for the rest of its version. We remove a feature only in a new version.
Limits can rise but do not fall
The limits on body size, node count, depth and timeline entries can rise within a version. They do not fall. A payload that is inside the limits today stays inside them. The one exception is a limit that Apple puts on widgets. If such a limit forces a change, the changelog says so.
Where Apple decides
Webhook Widget draws with Apple's frameworks. Some things can therefore change with an iOS release, whatever we promise. When that happens, we update the app as quickly as we can and say what changed in the changelog. We keep every protocol feature as close to its documented behaviour as iOS allows.
- Fonts and text sizes. The app sets text in Apple's system font at Apple's sizes. An iOS release can change the metrics of San Francisco or the Dynamic Type sizes. Text then gets wider or narrower, and the layout changes by the same rules. Content that fitted with spare room still fits.
- Widget sizes and shape. Apple sets the slot sizes, the corner radius and the families that a phone offers. iOS 26 made several of them bigger. Every request tells your server the exact size of the slot.
- Colours. Semantic colours come from the system, and Apple changes them. iOS 26 changed system blue. A semantic colour always follows the system. A hex value never changes.
- SF Symbols. Apple draws the symbols and adds new ones each year. Apple occasionally renames a symbol, and the old name keeps working. Apple decides how a symbol looks.
- Timers and live progress. The system sets the wording of a timer and the look of a live progress bar. The wording is in the person's own language.
- Refreshes and rendering modes. WidgetKit decides when a widget refreshes. WidgetKit also decides how a widget is drawn on a tinted or clear Home Screen and on the Lock Screen. See timelines.
If Apple removes something that a protocol feature depends on, we keep the feature as close to its documented behaviour as we can. In most cases the feature then draws nothing, so that it does not draw something wrong. The changelog says what changed.
Changelog
Version 1, revision 1 First release
Everything in the node reference today.
- Stacks, grids, text with spans, timers, symbols, images, gauges with live progress, shapes, spacers and dividers.
- The layout rules on the Layout page, text defaults, priorities, fill and min/max sizes, overflow with drop and more.
- Colours with opacity, borders, and the request fields family, w, h, scale, scheme, locale, tz, v and rev.
- The envelope fields v, refresh, view, entries, accessibility, url and preferredFamily.