Omniscio

Webhooks (receive HTTP POSTs into your inbox)

Webhooks run a local HTTP server that accepts incoming POST requests and turns each one into a row in the unified inbox, alongside Gmail, SMS, Slack, Telegram and RSS. Every source has its own URL path and bearer token, the channel is receive-only, and the page covers enabling it, adding and testing a source, the full set of response codes, and duplicate suppression.

On this page

What it is

Omniscio's webhook integration runs a local HTTP server that accepts incoming POST requests and surfaces each one as a row in the unified inbox — alongside Gmail, SMS, Slack, Telegram, and RSS. Each configured webhook source has a unique URL path and bearer token; every POST to that path becomes a "message" in that source's "conversation". This is a receive-only channel — there's no replying. Typical use cases: custom scripts on this machine that want to ping you, and — only once you front the receiver with a tunnel or reverse proxy of your own, see below — GitHub push/issue notifications, Stripe payment events, or Zapier/Make pipelines.

The receiver listens on 127.0.0.1 only — it is not reachable from the internet. The server binds the loopback address (there is no 0.0.0.0 bind and no configuration to make one), and Omniscio ships no tunnel, port-forward or hosted relay for it. So a third-party service like GitHub, Stripe or Zapier cannot POST to http://<your-host>:<port>/hooks/<sourceId> directly — its delivery will time out or 404 at its own end and nothing will ever appear in your inbox. A sender that lives on this same machine (a local script, a local container, a local automation) works as documented, because it reaches loopback too. To accept events from an external service you must run your own tunnel or reverse proxy in front of the port — a cloudflared / ngrok / Tailscale-Funnel style forwarder, or your own nginx/caddy proxy — point the third party at that public URL, and keep the bearer token secret since the URL is now internet-facing.

Where to find it

Settings → Webhooks carries the master toggle and the port the local server listens on, and each source you add there produces the URL and bearer token you hand to the sender. What arrives lands in the inbox as its own conversation, and the same payloads are visible to the automation engine and to the app-wide search.

How it behaves

How to use it

  1. Enable webhooks. Settings → Webhooks → toggle webhooksEnabled on. Pick the port the local HTTP server listens on (configurable via webhookPort in config-store).
  2. Add a webhook source. Each source gets a unique sourceId (URL slug) and a bearer token Omniscio auto-generates. Copy the resulting webhook URL — http://<your-host>:<port>/hooks/<sourceId> — into whatever sender is going to POST to it. That sender must be on this machine: the listener binds 127.0.0.1 and is not reachable from the internet, so pointing an external third-party service at this URL will not work — front the port with your own tunnel or reverse proxy first, and give the third party the public URL that comes out of it. The /hooks/ path segment is required: the server only answers POST /hooks/:sourceId, and any path without it returns a hard 404 Not found.
  3. Test it. From a terminal, curl -X POST -H "Authorization: Bearer <token>" -d '{"hello":"world"}' http://localhost:<port>/hooks/<sourceId>. Within a second the request should appear as a new row in the Omniscio inbox under that source's conversation.
  4. Read in the inbox. Click a webhook row to see the full conversation panel — every POST received shows the request method, headers, formatted JSON body (auto-pretty-printed), receive timestamp, and remote IP.
  5. Pair with automations. Webhook payloads flow through the standard Automation engine — keyword-match the body, route to email forward, summarize in the daily digest, or trigger a Claude session to react to the event.
  6. Signed requests and agent runs. A source can be switched to signed requests (an HMAC signing secret shown once, GitHub or generic header). It then accepts only requests whose signature over the exact body checks out — the bearer token stops working for it — and it can start agent runs directly, with filters, a prompt template, run-once keys, run and spending limits and approval. See webhook-agent-runs.md. For every source, credential headers (Authorization, cookies, anything named like a token, key, secret or signature) are replaced with [redacted] before the request is stored, so they never show in the inbox or on the phone.

How long a received message is kept

Webhook messages are deleted automatically, on two always-on rules, and neither has a setting. Do not treat the inbox as an event log:

  • 90 days, then gone. A sweep that runs at startup and every 6 hours deletes every received webhook message older than 90 days — read or unread. Nothing asks first and no toggle turns it off.
  • The newest 2,000 per source. Each source keeps at most 2,000 messages. When a new one pushes a source past that, the oldest is removed to make room, again read or unread.

If you need to keep an event, copy it somewhere of your own (or have an automation forward it) before either rule reaches it.

Last verified 2026-10-27