Webhook Widget
Menu The request

Protocol

The request

The widget sends a GET request with details about the slot it needs to fill. Use that information to return a layout that fits the phone and the widget size.

HTTP
GET /widget?key=s3cret
      &family=systemMedium
      &w=338&h=158
      &scale=3
      &scheme=dark
      &locale=en_GB
      &tz=Europe/London
      &v=1&rev=1
Host: you.example
Accept: */*

The widget keeps your own query parameters. If one of your parameters has the same name as a parameter that the widget sends, the widget sends your value. You can therefore put a token in ?key=….

What you receive

Field Type Description
family string systemSmall, systemMedium or systemLarge on the Home Screen. accessoryCircular, accessoryRectangular or accessoryInline on the Lock Screen.
w number Slot width in points, for this phone.
h number Slot height in points.
scale number Screen scale, 2 or 3. Multiply by w and h for pixels.
scheme string light or dark. This value is a hint. See the caveat on the request page.
locale string The person's locale, such as en_GB.
tz string IANA time zone, such as Europe/London.
v number Protocol version the app speaks.
rev number The revision of that version that the app understands. Send a node or field from a later revision only to an app whose rev is at least that revision. See versioning.

Build for the slot

The three families need different layouts. A small is about 158 points square. A medium is the same height and twice the width. A large is roughly square again at over twice the height. Branch on family and send a layout made for that family.

Node
app.get("/widget", (request, response) => {
  const family = request.query.family;

  // Answer with a layout that suits the slot rather than one that fits every slot.
  const view = family === "systemSmall"
    ? compactView()
    : detailedView();

  response.json({ v: 1, view });
});

w and h are the exact size of the slot in points on that phone. The size varies by screen. To render a bitmap, multiply by scale to get pixels. See bitmap mode.

The widget is also available in the three Lock Screen sizes. family can therefore be accessoryCircular, accessoryRectangular or accessoryInline. These slots are much smaller than any Home Screen slot. iOS always draws them in a vibrant mode with a single hue. This mode uses the same code path as a tinted Home Screen: opaque backgrounds are dropped, and accentable keeps a node in the bright group.

For a Lock Screen slot, return a few nodes, not the layout that you made for a medium. The previews on this site render only the three Home Screen families. Check a Lock Screen slot on a phone.

One payload, three slots
This payload is made for the small family. The larger families stretch the layout and do not reflow it. Nothing breaks, but the extra space stays empty. Branch on family to use the space.

Do not rely on scheme alone

scheme is the appearance at the time of the fetch. WidgetKit renders one timeline in both appearances. A payload fetched in light mode can still be on screen after the phone changes to dark mode. The app does not fetch again when the appearance changes.

Semantic colour names do not have this problem. The phone resolves them when it draws the widget, so "color": "primary" is correct in both appearances. Use scheme to choose a palette. Use semantic names to keep the widget readable. A bitmap cannot adapt to the appearance. This is the main reason to use nodes and not a bitmap.

Tinted Home Screen

If the person sets the Home Screen to a tinted style, iOS discards most of the colour in a widget and redraws the widget in a single hue. The request does not describe this mode, because iOS chooses the mode each time it draws the widget. iOS draws one payload in every mode that it needs. When the person restyles the Home Screen, iOS redraws the payload that is already on the phone. The app does not fetch again.

The phone handles tinted mode. This has two effects on a payload. First, an opaque background is dropped in these modes. If it stayed, the background would have the same hue as the text on it, and the widget would look blank. Second, accentable: true on a node keeps that node in the bright group and not the dim group. Use it to keep a number legible when the colour is gone.

Inspect a real request

You cannot attach a debugger to a widget extension. To see the request that your phone sends, use the endpoint below as the URL of a widget. The widget shows the request that the phone sent.

URL
https://webhookwidget.com/api/echo
What /api/echo returns
The values above are from a sample request. On a phone, the values are from that phone. Use them to find the exact slot size for a bitmap. The endpoint branches on family. The medium shows the values in two columns. The small shows only the four rows that fit.

Caching

The app caches responses on the phone and uses the cached response when a fetch fails. If a server is down for a short time, the widget shows the last good response with a small orange staleness dot, not an error. The app builds cache keys from the URL with any credentials removed.

For bitmap responses, Cache-Control: max-age is the only way to ask for a refresh interval. A bitmap response has no envelope to contain refresh.