Webhook Widget
Menu Quickstart

Start

Quickstart

You need an HTTPS URL that returns JSON. Start with one of the examples, then replace it with your own endpoint.

Get Webhook Widget on the App Store. It runs on iPhone with iOS 26.2 or later, and on iPad with iPadOS 26.2 or later.

1. Add an endpoint

A hook is a URL saved in the app under a name you choose. The app includes a few examples, so you can try a real widget before writing a server. Adding one is free, works on your Home Screen without the trial, and can be undone at any time.

You can also add a hook by scanning a QR code with the iPhone camera. The webhookwidget CLI draws one for your own endpoint, with its credential if it has one (npx webhookwidget --help lists the options):

Terminal
npx webhookwidget qr --name "My widget" --url https://example.com/widget

A code someone else shares from the app works the same way, and a hook shared with you is free on your Home Screen, for good.

URL
https://webhookwidget.com/demo/hello

Every demo on this site is served the same way, at /demo/<id>, with timestamps generated at the moment of the request. To add another, tap Add Hook and give it a name and an address.

2. Add the widget

Touch and hold an empty area of the Home Screen, tap Edit then Add Widget, and choose Webhook Widget at the size you want. A new widget starts on your first hook; to point it at a different one, touch and hold it, choose Edit Widget, and pick the name.

What that URL returns
json
{
  "v": 1,
  "preferredFamily": "systemSmall",
  "refresh": 900,
  "accessibility": "Hello, World! Fetched from webhookwidget.com just now",
  "url": "https://webhookwidget.com/docs/quickstart/",
  "view": {
    "type": "vstack",
    "align": "leading",
    "spacing": 0,
    "padding": 16,
    "children": [
      {
        "type": "hstack",
        "spacing": 5,
        "children": [
          {
            "type": "symbol",
            "name": "link",
            "style": "caption2",
            "weight": "bold",
            "color": "orange"
          },
          {
            "type": "text",
            "text": "WEBHOOK WIDGET",
            "style": "caption2",
            "weight": "bold",
            "color": "secondary"
          }
        ]
      },
      {"type": "spacer"},
      {
        "type": "text",
        "text": "Hello, World!",
        "style": "title2",
        "weight": "bold",
        "design": "rounded",
        "color": "primary",
        "lines": 2
      },
      {"type": "spacer"},
      {
        "type": "text",
        "text": "FETCHED",
        "style": "caption2",
        "weight": "semibold",
        "color": "tertiary"
      },
      {
        "type": "timer",
        "from": "2026-08-11T08:40:00Z",
        "style": "relative",
        "size": 13,
        "color": "secondary"
      }
    ]
  }
}

3. Return your own JSON

The smallest valid response is a version and a single node. Everything else in the protocol is optional.

json
{
  "v": 1,
  "view": { "type": "text", "text": "Hello from my server" }
}

This handler returns a heading, a number and a gauge. It reads the appearance from the query string:

Node (Express)
import express from "express";

const app = express();

app.get("/widget", (request, response) => {
  const { family, w, h, scheme } = request.query;

  response.json({
    v: 1,
    refresh: 900,
    accessibility: "Four tasks left today",
    view: {
      type: "vstack",
      align: "leading",
      spacing: 2,
      padding: 16,
      bg: scheme === "dark" ? "#14181F" : "white",
      children: [
        { type: "text", text: "TODAY", style: "caption2",
          weight: "bold", color: "secondary" },
        { type: "text", text: "4 left", style: "largeTitle",
          weight: "bold", design: "rounded" },
        { type: "spacer" },
        { type: "gauge", value: 6, min: 0, max: 10, tint: "green" },
      ],
    },
  });
});

app.listen(3000);
Python (Flask)
from flask import Flask, jsonify, request

app = Flask(__name__)

@app.get("/widget")
def widget():
    dark = request.args.get("scheme") == "dark"
    return jsonify({
        "v": 1,
        "refresh": 900,
        "accessibility": "Four tasks left today",
        "view": {
            "type": "vstack",
            "align": "leading",
            "spacing": 2,
            "padding": 16,
            "bg": "#14181F" if dark else "white",
            "children": [
                {"type": "text", "text": "TODAY", "style": "caption2",
                 "weight": "bold", "color": "secondary"},
                {"type": "text", "text": "4 left", "style": "largeTitle",
                 "weight": "bold", "design": "rounded"},
                {"type": "spacer"},
                {"type": "gauge", "value": 6, "min": 0, "max": 10, "tint": "green"},
            ],
        },
    })
The response above

4. Choose a refresh interval

refresh is the number of seconds the widget waits before it fetches again. The app limits it to between 5 minutes and a day. iOS decides when each fetch happens, so the interval can be longer than the value you set.

To keep the widget correct between fetches, return several future states in one response. See timelines.

Next steps