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):
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.
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.
{
"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.
{
"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:
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); 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"},
],
},
}) 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
- Node reference: every node and every field, each with a live demo.
- Timelines and refreshes: how to keep a widget correct between fetches.
- Authentication: four ways to keep the endpoint private.
- Playground: write a payload and see it drawn as you type.