Webhook Widget
Menu Authentication

Protocol

Authentication

The widget sends the same token or password with every request. Use the format your server already supports. You can configure the last three options in the app.

SchemeHow to configureWhat is sent
Query token Write it into the URL: ?key=s3cret Your parameter, preserved exactly
Basic, no UI https://user:pass@host/feed Authorization: Basic …
Basic Hook → Authentication → Basic Authorization: Basic …
Bearer Hook → Authentication → Bearer token Authorization: Bearer …
Custom header Hook → Authentication → Custom header e.g. X-API-Key: …
Zero-configuration forms
https://you.example/widget?key=s3cret

# Or with credentials in the URL, which are moved into a header before the
# request leaves the device:
https://user:pass@you.example/widget

The app moves a user:pass credential from the URL into a header before it sends the request. URLs appear in caches, logs and error messages. A header does not. A scheme that you set on the hook overrides a credential in the URL.

Verifying on your side
app.get("/widget", (request, response) => {
  const token = request.headers.authorization?.replace(/^Bearer /, "");
  if (token !== process.env.WIDGET_TOKEN) {
    return response.status(401).json({ error: "unauthorized" });
  }
  response.json({ view: buildView(request.query) });
});

Rules the app applies

  • The app never sends a credential over plain HTTP. This is also true when the HTTPS check is off for local development.
  • The app removes the credential header on a redirect to a different host. A redirect to the same host keeps it.
  • A password never appears in a cache filename, an error message or the app. The app makes cache keys from the URL without its credential. Where the app shows a URL, it replaces the credential with •••.
  • The app checks for HTTPS at every redirect, and on the first request.

Where credentials are stored

The app stores a hook's URL and credential together, in the container that the app and the widget share. The widget on the Home Screen holds only the hook's name. The credential is not in WidgetKit's configuration store.