Webhook Widget
Menu Limits and errors

Protocol

Limits and errors

Widget extensions have strict resource limits. The app enforces all of the limits below. The Notes column says what the app does when a response is over a limit. The app rejects the response unless a note says that it drops the extra items or changes the value.

LimitValueNotes
JSON body 256 KB The app measures the payload before it decodes it. The app rejects a larger payload and does not parse it.
Image body 2 MB Applies to `image` nodes and to bitmap responses.
Image pixels 2000 px On the longest side.
Nodes 300 Counted across the whole tree, including every entry.
Depth 12 How far stacks may nest.
Timeline entries 60 The app drops extra entries. This is not an error.
Entry spacing 5 minutes The app drops entries that are closer together, because WidgetKit ignores them.
Refresh 300–86400 s The app clamps values outside the range. It does not reject them.
Request timeout 10 s
Redirects 3 The app checks for HTTPS again at every redirect.

Invalid payloads

A decode failure produces a specific message, not a generic one. If there is no cached response, the widget shows only the message, under a small “Couldn't load” heading. The previews below show this error view. The wording comes from the same engine as every other preview on this site.

an unknown node type is refused, lowercased in the message
json
{"v": 1, "view": {"type": "Marquee"}}
text without a text field is refused
json
{"v": 1, "view": {"type": "text"}}
a colour without the hash is refused
json
{"v": 1, "view": {"type": "text", "text": "x", "color": "3DDC84"}}
a non-http image scheme is refused
json
{"v": 1, "view": {"type": "image", "url": "file:///etc/passwd"}}

Decode errors

These cases come from web/conformance/decode-cases.json. Both test suites run this corpus: the Swift decoder in the app and the Rust engine that draws the previews on this site. Both implementations are tested against every message on this page.

CaseMessage
an unknown node type is refused, lowercased in the message Unknown node type "marquee"
text without a text field is refused Missing required field "text"
a five-digit hex value is refused Invalid value for "color": #12345
non-hex characters are refused Invalid value for "color": #GGGGGG
a colour without the hash is refused Invalid value for "color": 3DDC84
font style values are case-sensitive generic decoding error
timer without a date is refused Missing required field "until"
timer style names the timer style, not a font style generic decoding error
a date with no timezone is refused generic decoding error
month 13 is refused generic decoding error
day 32 is refused generic decoding error
gauge without a value is refused Missing required field "value"
an inverted gauge range is refused Invalid value for "max": 2.0
a zero-width gauge range is refused Invalid value for "max": 5.0
a non-http image scheme is refused Invalid value for "url": file:///etc/passwd
a schemeless image url is refused Invalid value for "url": example.com/a.png
a payload with neither view nor entries is refused Response contained no "view" or "entries"
a payload without v is refused Missing required field "v"
a future protocol version is refused rather than misread Payload version 2 is newer than this app supports
a view nested one level too deep is refused View tree nested deeper than 12 levels
a view one node over the limit is refused View tree exceeds 300 nodes
the node budget spans every entry, not each one separately View tree exceeds 300 nodes
padding that is neither a number nor an object is refused generic decoding error
a padding edge that is not a number is refused generic decoding error
w refuses any other string Invalid value for "w": wide
an opacity over 100 is refused Invalid value for "color": red/120
an opacity with a sign is refused Invalid value for "color": red/-5
an empty opacity is refused Invalid value for "color": red/
a span without text is refused Missing required field "text"
a text with neither text nor spans is refused Missing required field "text"
text defaults must be an object Invalid value for "text": footnote
a symbol without a name is refused Missing required field "name"
an unknown symbol mode is refused generic decoding error
a border object needs a colour Missing required field "color"
a live gauge with only from is refused Missing required field "until"
a live gauge with only until is refused Missing required field "from"
a grid row with more cells than columns is refused Invalid value for "rows": row 1 has 3 cells for 2 columns
a grid row object needs cells Missing required field "cells"
an unknown overflow is refused Invalid value for "overflow": hide
a preferredFamily that is not a string is refused generic decoding error

Where the table says generic decoding error, the payload is still refused. The two runtimes word the error differently. The corpus therefore asserts that the payload fails, and does not assert the wording.

Transport failures

ConditionMessage
Not HTTPSyou.example is not HTTPS
Credentials over plain HTTP Refusing to send credentials over plain HTTP to you.example
Non-2xx statusServer returned HTTP 503
Body too large Response is 400000 bytes, over the 262144 byte limit
Wrong content type Cannot render Content-Type "text/html"
Image too large Image is 4000px on its longest side, over the 2000px limit
Undecodable imageResponse was not a decodable image
Redirect loopExceeded 3 redirects

Counting nodes

The 300-node limit counts the whole response, not each entry. A timeline of 12 entries with 30 nodes each has 360 nodes, and the app refuses it. If you generate rows in a loop, set a maximum for the loop.

Depth is counted the same way. The limit is 12 levels. If a layout is close to 12 levels, remove the containers that it does not need.