Webhook Widget
Menu Timelines and refreshes

Protocol

Timelines and refreshes

iOS decides when a widget fetches new data. You cannot start a fetch on demand. Use timelines for future states that you know, and timers for anything based on the clock.

How refreshes work

refresh is the earliest time at which you want the next fetch. It is a request to iOS, not a schedule. iOS decides when each fetch happens, and that is some time after the time you asked for.

iOS manages a refresh budget for each widget. You cannot see the budget, and you cannot use it faster. If a widget asks too often, iOS grants a smaller share of the fetches that it asked for. Return payloads that stay correct between fetches.

A widget that asks for a fetch every 15 minutes gets only some of those fetches during the day. One payload with four entries is correct for the same day. Short interval refresh: 900 asked all day · granted occasionally · wrong in between Timeline 4 entries Standup 09:00 Design review 11:30 1:1 14:00 Retro 16:30 one fetch, at 09:00 one fetch · correct at every moment
Both rows show the same working day. In the first row, the widget asks for a fetch every 15 minutes and iOS grants some of them. In the second row, one fetch returns four entries.

Entries

An entry is a view with a time. If you send several entries, the phone renders each entry at its time. The phone does not contact your server again.

json
{
  "v": 1,
  "refresh": 3600,
  "entries": [
    {"at": "2026-08-11T09:00:00Z", "view": {"type": "text", "text": "Platform 3"}},
    {"at": "2026-08-11T11:30:00Z", "view": {"type": "text", "text": "Platform 7"}},
    {"at": "2026-08-11T14:00:00Z", "view": {"type": "text", "text": "Platform 3"}}
  ]
}

Put everything that you know at request time into the timeline. Examples are a calendar that you have already fetched, a train schedule, a shift rota and a countdown to a fixed date. The next fetch brings the data that you cannot predict.

Four entries in one payload Large
json
{
  "v": 1,
  "preferredFamily": "systemLarge",
  "refresh": 3600,
  "accessibility": "Four meetings today, next is standup at 9",
  "entries": [
    {
      "at": "2026-08-11T09:00:00Z",
      "view": {
        "type": "vstack",
        "align": "leading",
        "spacing": 10,
        "padding": 16,
        "bg": "white",
        "children": [
          {
            "type": "hstack",
            "children": [
              {
                "type": "vstack",
                "align": "leading",
                "spacing": -2,
                "children": [
                  {
                    "type": "text",
                    "text": "TUESDAY",
                    "style": "caption2",
                    "weight": "bold",
                    "color": "red"
                  },
                  {
                    "type": "text",
                    "text": "11",
                    "size": 32,
                    "weight": "regular",
                    "color": "primary"
                  }
                ]
              },
              {"type": "spacer"},
              {
                "type": "text",
                "text": "4 to go",
                "style": "caption",
                "weight": "semibold",
                "color": "secondary"
              }
            ]
          },
          {
            "type": "text",
            "text": "NOW",
            "style": "caption2",
            "weight": "bold",
            "color": "blue"
          },
          {
            "type": "hstack",
            "spacing": 10,
            "w": "fill",
            "padding": 10,
            "bg": "blue/12",
            "corner": 10,
            "children": [
              {"type": "rect", "w": 4, "fill": "blue", "corner": 2},
              {
                "type": "vstack",
                "align": "leading",
                "spacing": 2,
                "children": [
                  {
                    "type": "text",
                    "text": "Standup",
                    "style": "title3",
                    "weight": "semibold",
                    "color": "primary",
                    "lines": 2
                  },
                  {
                    "type": "text",
                    "text": "09:00 – 09:15",
                    "style": "subheadline",
                    "weight": "medium",
                    "color": "blue",
                    "monoDigits": true
                  },
                  {
                    "type": "text",
                    "text": "Team sync · Zoom",
                    "style": "footnote",
                    "color": "secondary",
                    "lines": 1
                  }
                ]
              },
              {"type": "spacer"}
            ]
          },
          {
            "type": "text",
            "text": "LATER",
            "style": "caption2",
            "weight": "bold",
            "color": "tertiary"
          },
          {
            "type": "vstack",
            "align": "leading",
            "spacing": 6,
            "overflow": "drop",
            "more": {
              "type": "text",
              "text": "+{count} more",
              "style": "caption",
              "color": "secondary"
            },
            "children": [
              {
                "type": "hstack",
                "spacing": 8,
                "children": [
                  {"type": "rect", "w": 3, "fill": "purple", "corner": 1.5},
                  {
                    "type": "vstack",
                    "align": "leading",
                    "spacing": 0,
                    "children": [
                      {
                        "type": "text",
                        "text": "Design review",
                        "style": "subheadline",
                        "weight": "medium",
                        "color": "primary",
                        "lines": 1
                      },
                      {
                        "type": "text",
                        "text": "11:30",
                        "style": "caption",
                        "color": "secondary",
                        "monoDigits": true
                      }
                    ]
                  }
                ]
              },
              {
                "type": "hstack",
                "spacing": 8,
                "children": [
                  {"type": "rect", "w": 3, "fill": "teal", "corner": 1.5},
                  {
                    "type": "vstack",
                    "align": "leading",
                    "spacing": 0,
                    "children": [
                      {
                        "type": "text",
                        "text": "1:1 with Alex",
                        "style": "subheadline",
                        "weight": "medium",
                        "color": "primary",
                        "lines": 1
                      },
                      {
                        "type": "text",
                        "text": "14:00",
                        "style": "caption",
                        "color": "secondary",
                        "monoDigits": true
                      }
                    ]
                  }
                ]
              },
              {
                "type": "hstack",
                "spacing": 8,
                "children": [
                  {"type": "rect", "w": 3, "fill": "orange", "corner": 1.5},
                  {
                    "type": "vstack",
                    "align": "leading",
                    "spacing": 0,
                    "children": [
                      {
                        "type": "text",
                        "text": "Sprint 42 retro",
                        "style": "subheadline",
                        "weight": "medium",
                        "color": "primary",
                        "lines": 1
                      },
                      {
                        "type": "text",
                        "text": "16:30",
                        "style": "caption",
                        "color": "secondary",
                        "monoDigits": true
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {"type": "spacer"}
        ]
      }
    },
    {
      "at": "2026-08-11T11:30:00Z",
      "view": {
        "type": "vstack",
        "align": "leading",
        "spacing": 10,
        "padding": 16,
        "bg": "white",
        "children": [
          {
            "type": "hstack",
            "children": [
              {
                "type": "vstack",
                "align": "leading",
                "spacing": -2,
                "children": [
                  {
                    "type": "text",
                    "text": "TUESDAY",
                    "style": "caption2",
                    "weight": "bold",
                    "color": "red"
                  },
                  {
                    "type": "text",
                    "text": "11",
                    "size": 32,
                    "weight": "regular",
                    "color": "primary"
                  }
                ]
              },
              {"type": "spacer"},
              {
                "type": "text",
                "text": "3 to go",
                "style": "caption",
                "weight": "semibold",
                "color": "secondary"
              }
            ]
          },
          {
            "type": "text",
            "text": "NOW",
            "style": "caption2",
            "weight": "bold",
            "color": "purple"
          },
          {
            "type": "hstack",
            "spacing": 10,
            "w": "fill",
            "padding": 10,
            "bg": "purple/12",
            "corner": 10,
            "children": [
              {"type": "rect", "w": 4, "fill": "purple", "corner": 2},
              {
                "type": "vstack",
                "align": "leading",
                "spacing": 2,
                "children": [
                  {
                    "type": "text",
                    "text": "Design review",
                    "style": "title3",
                    "weight": "semibold",
                    "color": "primary",
                    "lines": 2
                  },
                  {
                    "type": "text",
                    "text": "11:30 – 12:30",
                    "style": "subheadline",
                    "weight": "medium",
                    "color": "purple",
                    "monoDigits": true
                  },
                  {
                    "type": "text",
                    "text": "With Priya and Sam · Room 4B",
                    "style": "footnote",
                    "color": "secondary",
                    "lines": 1
                  }
                ]
              },
              {"type": "spacer"}
            ]
          },
          {
            "type": "text",
            "text": "LATER",
            "style": "caption2",
            "weight": "bold",
            "color": "tertiary"
          },
          {
            "type": "vstack",
            "align": "leading",
            "spacing": 6,
            "overflow": "drop",
            "more": {
              "type": "text",
              "text": "+{count} more",
              "style": "caption",
              "color": "secondary"
            },
            "children": [
              {
                "type": "hstack",
                "spacing": 8,
                "children": [
                  {"type": "rect", "w": 3, "fill": "teal", "corner": 1.5},
                  {
                    "type": "vstack",
                    "align": "leading",
                    "spacing": 0,
                    "children": [
                      {
                        "type": "text",
                        "text": "1:1 with Alex",
                        "style": "subheadline",
                        "weight": "medium",
                        "color": "primary",
                        "lines": 1
                      },
                      {
                        "type": "text",
                        "text": "14:00",
                        "style": "caption",
                        "color": "secondary",
                        "monoDigits": true
                      }
                    ]
                  }
                ]
              },
              {
                "type": "hstack",
                "spacing": 8,
                "children": [
                  {"type": "rect", "w": 3, "fill": "orange", "corner": 1.5},
                  {
                    "type": "vstack",
                    "align": "leading",
                    "spacing": 0,
                    "children": [
                      {
                        "type": "text",
                        "text": "Sprint 42 retro",
                        "style": "subheadline",
                        "weight": "medium",
                        "color": "primary",
                        "lines": 1
                      },
                      {
                        "type": "text",
                        "text": "16:30",
                        "style": "caption",
                        "color": "secondary",
                        "monoDigits": true
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {"type": "spacer"}
        ]
      }
    },
    {
      "at": "2026-08-11T14:00:00Z",
      "view": {
        "type": "vstack",
        "align": "leading",
        "spacing": 10,
        "padding": 16,
        "bg": "white",
        "children": [
          {
            "type": "hstack",
            "children": [
              {
                "type": "vstack",
                "align": "leading",
                "spacing": -2,
                "children": [
                  {
                    "type": "text",
                    "text": "TUESDAY",
                    "style": "caption2",
                    "weight": "bold",
                    "color": "red"
                  },
                  {
                    "type": "text",
                    "text": "11",
                    "size": 32,
                    "weight": "regular",
                    "color": "primary"
                  }
                ]
              },
              {"type": "spacer"},
              {
                "type": "text",
                "text": "2 to go",
                "style": "caption",
                "weight": "semibold",
                "color": "secondary"
              }
            ]
          },
          {
            "type": "text",
            "text": "NOW",
            "style": "caption2",
            "weight": "bold",
            "color": "teal"
          },
          {
            "type": "hstack",
            "spacing": 10,
            "w": "fill",
            "padding": 10,
            "bg": "teal/12",
            "corner": 10,
            "children": [
              {"type": "rect", "w": 4, "fill": "teal", "corner": 2},
              {
                "type": "vstack",
                "align": "leading",
                "spacing": 2,
                "children": [
                  {
                    "type": "text",
                    "text": "1:1 with Alex",
                    "style": "title3",
                    "weight": "semibold",
                    "color": "primary",
                    "lines": 2
                  },
                  {
                    "type": "text",
                    "text": "14:00 – 14:30",
                    "style": "subheadline",
                    "weight": "medium",
                    "color": "teal",
                    "monoDigits": true
                  },
                  {
                    "type": "text",
                    "text": "Career check-in",
                    "style": "footnote",
                    "color": "secondary",
                    "lines": 1
                  }
                ]
              },
              {"type": "spacer"}
            ]
          },
          {
            "type": "text",
            "text": "LATER",
            "style": "caption2",
            "weight": "bold",
            "color": "tertiary"
          },
          {
            "type": "vstack",
            "align": "leading",
            "spacing": 6,
            "overflow": "drop",
            "more": {
              "type": "text",
              "text": "+{count} more",
              "style": "caption",
              "color": "secondary"
            },
            "children": [
              {
                "type": "hstack",
                "spacing": 8,
                "children": [
                  {"type": "rect", "w": 3, "fill": "orange", "corner": 1.5},
                  {
                    "type": "vstack",
                    "align": "leading",
                    "spacing": 0,
                    "children": [
                      {
                        "type": "text",
                        "text": "Sprint 42 retro",
                        "style": "subheadline",
                        "weight": "medium",
                        "color": "primary",
                        "lines": 1
                      },
                      {
                        "type": "text",
                        "text": "16:30",
                        "style": "caption",
                        "color": "secondary",
                        "monoDigits": true
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {"type": "spacer"}
        ]
      }
    },
    {
      "at": "2026-08-11T16:30:00Z",
      "view": {
        "type": "vstack",
        "align": "leading",
        "spacing": 10,
        "padding": 16,
        "bg": "white",
        "children": [
          {
            "type": "hstack",
            "children": [
              {
                "type": "vstack",
                "align": "leading",
                "spacing": -2,
                "children": [
                  {
                    "type": "text",
                    "text": "TUESDAY",
                    "style": "caption2",
                    "weight": "bold",
                    "color": "red"
                  },
                  {
                    "type": "text",
                    "text": "11",
                    "size": 32,
                    "weight": "regular",
                    "color": "primary"
                  }
                ]
              },
              {"type": "spacer"},
              {
                "type": "text",
                "text": "1 to go",
                "style": "caption",
                "weight": "semibold",
                "color": "secondary"
              }
            ]
          },
          {
            "type": "text",
            "text": "NOW",
            "style": "caption2",
            "weight": "bold",
            "color": "orange"
          },
          {
            "type": "hstack",
            "spacing": 10,
            "w": "fill",
            "padding": 10,
            "bg": "orange/12",
            "corner": 10,
            "children": [
              {"type": "rect", "w": 4, "fill": "orange", "corner": 2},
              {
                "type": "vstack",
                "align": "leading",
                "spacing": 2,
                "children": [
                  {
                    "type": "text",
                    "text": "Sprint 42 retro",
                    "style": "title3",
                    "weight": "semibold",
                    "color": "primary",
                    "lines": 2
                  },
                  {
                    "type": "text",
                    "text": "16:30 – 17:30",
                    "style": "subheadline",
                    "weight": "medium",
                    "color": "orange",
                    "monoDigits": true
                  },
                  {
                    "type": "text",
                    "text": "Whole team · Big room",
                    "style": "footnote",
                    "color": "secondary",
                    "lines": 1
                  }
                ]
              },
              {"type": "spacer"}
            ]
          },
          {
            "type": "text",
            "text": "Nothing else today.",
            "style": "subheadline",
            "color": "secondary"
          },
          {"type": "spacer"}
        ]
      }
    }
  ]
}
The entry control shows each entry of the timeline in turn. Each entry is a complete view.

Entry rules

  • The app sorts entries by at. You do not have to send them in order.
  • The app drops entries that are less than five minutes apart, because WidgetKit ignores them. Two entries 30 seconds apart become one entry, with no error.
  • The app keeps at most 60 entries. It discards the rest.
  • The 300-node limit counts all entries together, not each entry. If the views are large, send as many future states as fit. The next fetch brings the rest. The team rota example sends the next few shift changes and asks for a refresh every hour.
  • An entry with no at starts immediately. A plain view is a single entry with no time.
  • An entry can have its own accessibility. It replaces the accessibility of the envelope while that entry is on screen. Set it when the entries say different things, because one label cannot be correct for all of them.

Use timers for countdowns

A timer node updates on the phone every second and needs no timeline entry. If a value depends only on the clock, use a timer. Do not send a number that your server calculates again for each fetch.

Two ways to show six minutes
// Refreshing every minute to update a countdown: you will not get the refreshes,
// and the widget will be wrong between the ones you do get.
{ "v": 1, "refresh": 60, "view": { "type": "text", "text": "6 min" } }

// The device counts down on its own. One fetch covers the whole wait.
{ "v": 1, "refresh": 900, "view": { "type": "timer", "until": "2026-08-11T09:06:00Z" } }
Five ways to render one date

Choosing an interval

Kind of dataIntervalWhy
Anything derived from the clock 3600+ Use a timer node. The phone counts without a fetch.
A schedule you already know 3600–21600 Send it as entries. Fetch again only when the schedule can change.
Metrics, queues, build status 900–1800 You cannot predict this data. Use the refresh budget for it.
Anything faster than five minutes None The app clamps the value to 300, and iOS does not fetch that often. A widget is not a live dashboard.

The budget is for each widget instance. A person who adds the same URL in three sizes causes three separate sets of fetches. Make payloads cheap to generate.