Protocol
The response
A response can contain a JSON view or an image. The Content-Type header tells
the widget which one it received.
| Content-Type | Behaviour |
|---|---|
application/json, */*+json | The app parses the body as the envelope below. |
image/* | The app draws the image edge to edge, and the image fills the widget. See bitmap mode. |
| Anything else |
The app checks whether the body starts with { or an image header.
If the body starts with neither, the app rejects the response.
|
The envelope
{
"v": 1,
"refresh": 900,
"accessibility": "Bus 42 arriving in 6 minutes",
"url": "https://you.example/open",
"view": { "type": "vstack", "children": [] }
} | Field | Type | Default | Description |
|---|---|---|---|
v | number | required | Protocol version, currently 1. The app refuses a payload that names no version. The app also refuses a version above the versions that it knows. |
refresh | number | 900 | Seconds until the next fetch. Clamped to 300–86400. |
view | node | — | The view tree. It is the same as entries with one entry. |
entries | entry[] | — | Future states, each { "at": ISO-8601, "view": node }, optionally with its own accessibility. Use this or view, not both. |
accessibility | string | — | VoiceOver label for every entry. Without it, VoiceOver reads the widget's text nodes. An entry's own accessibility replaces this label while that entry is on screen. |
url | string | — | The URL that opens when the person taps the widget. Use a web address or another app's scheme. For example, a rota widget can open the rota app. The app refuses its own webhookwidget: scheme. The app also refuses javascript:, data: and file:. |
preferredFamily | string | — | The size you designed the widget for: systemSmall, systemMedium or systemLarge (or a Lock Screen family). The app previews the widget at this size. The app names this size when it shows how to add the widget. On the Home Screen, the widget draws at the size that the person added. Continue to answer the family of each request. The app ignores a value that it does not know. |
A payload needs either view or entries. view is a
short form of a single entry that starts now. Anything that you can write with
view, you can also write with entries. Start with
view. Use entries when you need more than one
state.
VoiceOver text: accessibility
Without this field, VoiceOver reads the text nodes of the widget in order. For the departures example, VoiceOver reads “Camden Road Southbound 42 Kings Cross 6:00”. With this field, VoiceOver reads the sentence that you write.
Write a sentence that a person would say. This field has no effect on the layout. The note under every preview on this site shows what VoiceOver reads.
Tapping the widget: url
The widget is a single tap target. A tap opens url. The value can be a website
or a URL scheme that your own app registers. Use a scheme of your own app to open a
specific screen of that app.
{
"v": 1,
"url": "https://webhookwidget.com/docs/response/",
"accessibility": "Open the response documentation",
"view": {
"type": "vstack",
"align": "leading",
"spacing": 4,
"padding": 16,
"bg": "#151A21",
"children": [
{
"type": "text",
"text": "TAP TARGET",
"style": "caption2",
"weight": "bold",
"color": "#6D7786"
},
{
"type": "text",
"text": "One link",
"style": "title2",
"weight": "bold",
"color": "white"
},
{
"type": "text",
"text": "The whole widget opens the url in the envelope.",
"style": "footnote",
"color": "#9AA4B2",
"lines": 3
},
{"type": "spacer"},
{
"type": "text",
"text": "webhookwidget.com",
"style": "caption2",
"color": "cyan"
}
]
}
} Versioning
v states the protocol version of the payload. Every payload must contain
v. The current value is "v": 1. The app refuses a payload with a
version above the version that the app knows. The app also refuses a payload with no
version.
If a fetch fails
A failed fetch does not blank the widget. The widget shows the last successful response again, with a small orange staleness dot. The person sees old data that is marked as old, not an error.
This applies to network failures, non-2xx statuses, oversized bodies and payloads that do not decode. The exact wording of each decode failure is on limits and errors. That page lists every message and has live examples of some of them.