Your agents’ events,
where you want them.
Gnista already knows when each of your coding agents is working, needs you or is done. Webhooks pass that on: a message in Slack, Discord or Microsoft Teams, a red lamp in Home Assistant or Apple Home, a line in your own log. Here’s how to set each up, and what it takes without Gnista.
Updated
The short answer
In Gnista’s Settings ▸ Notifications ▸ Webhooks, click Add, choose Slack, Discord, Microsoft Teams or Home Assistant or Other and paste the URL, or choose Shortcut and pick one of your shortcuts. From then on, the changes you pick go there from every agent Gnista connects: Claude Code, Codex, Gemini CLI, OpenCode and the rest, on your Mac or over SSH.
With Gnista
- Download Gnista, open it and tick your agents.
- Open Settings ▸ Notifications and find Webhooks, tagged Experimental.
- Click Add and choose: Slack, Discord or Microsoft Teams for a chat message, Home Assistant or Other for Gnista JSON, a small JSON for Home Assistant or your own script, or Shortcut to run one of your shortcuts with that JSON.
- Paste the URL, or pick the shortcut. For Gnista JSON you can also set a Secret, sent as a Bearer token.
- In the row’s ⋯ menu, choose its Events: Everything, Needs you only, or Needs you and finished turns. Chats start with Needs you only, so a channel isn’t flooded; Gnista JSON and shortcuts start with Everything.
- Choose Test in the same menu. One sample goes out, or the shortcut runs once, and the row says how it went. Each webhook has its own switch, to pause it without removing it.
Slack
Slack posts to a channel through an incoming webhook. In your Slack app’s settings at api.slack.com/apps (opens in a new tab) (create an app if you have none), open Incoming Webhooks, turn them on, click Add New Webhook to Workspace and pick a channel. The URL starts with https://hooks.slack.com/services/. Each change becomes one line, worded like the Mac’s notification and in the app’s language: the agent, what happened, the project, and what it asks.
Discord
In Discord, open the channel’s Edit Channel ▸ Integrations ▸ Webhooks, click New Webhook, then Copy Webhook URL. Messages read as they do in Slack, and never ping anyone: @everyone, @here and other mentions are switched off.
Microsoft Teams
Teams takes webhooks through its Workflows app; the old Office 365 connectors are being retired. In the channel, open ⋯ ▸ Workflows, choose the template Send webhook alerts to a channel, pick the team and channel, and click Save. Copy the webhook URL it shows, and add it in Gnista as Microsoft Teams. Each change arrives as a card with the same one line Slack gets.
Mattermost and Rocket.Chat accept Slack’s format: add their incoming webhook’s URL as Slack.
Home Assistant
Make an automation with a webhook trigger (opens in a new tab): POST allowed, and an id that’s hard to guess. Add a webhook in Gnista with Home Assistant or Other and paste http://homeassistant.local:8123/api/webhook/ followed by that id. The id is the secret, so leave Gnista’s Secret empty.
This automation turns a lamp red while an agent needs you, and off again when it moves on:
alias: Agent needs me
triggers:
- trigger: webhook
webhook_id: gnista-pick-something-long
allowed_methods: [POST]
local_only: true
actions:
- choose:
- conditions: "{{ trigger.json.event == 'needsYou' }}"
sequence:
- action: light.turn_on
target: { entity_id: light.desk }
data: { color_name: red }
- conditions: "{{ trigger.json.event in ['working', 'done', 'idle', 'ended'] }}"
sequence:
- action: light.turn_off
target: { entity_id: light.desk }With several agents at once, the last change wins. For “any session needs me”, keep a count in a helper.
Apple Home
On a Mac, Gnista can’t control HomeKit directly: Apple keeps Home to apps built for iPhone and iPad. A shortcut can, so Gnista runs one, with Gnista JSON as its input. It runs on your Mac, so the Mac has to be awake.
In the Shortcuts app, make a shortcut that does this:
- Get Dictionary from Input, then Get Dictionary Value for
event. - If the value is
needsYou: Control Home, or a scene, to turn a light on and red. - Otherwise: Control Home to turn that light off.
- In Gnista, click Add ▸ Shortcut and pick it. Leave Events at Everything, so the light goes off again when the agent moves on.
Google Home
Google Home has no incoming webhook and no public web API that could switch a light from a Mac. Its developer APIs, the Home APIs, are for Android and iPhone apps, and its automations can’t start from a web request.
What works: Home Assistant (opens in a new tab). Most lights in Google Home, such as Matter, Philips Hue and Nest devices, can be added to Home Assistant too, and a Matter device can be shared with both at once. The automation above then works as it is.
Without a server: IFTTT’s Webhooks (opens in a new tab) trigger Receive a web request with a JSON payload accepts Gnista JSON, and IFTTT’s services for Philips Hue, LIFX, Govee and other lights can change a light’s colour. Add the trigger’s URL, https://maker.ifttt.com/trigger/ with your event name and key, in Gnista with Home Assistant or Other, and set Events to Needs you only, so the applet runs only when an agent needs you. The Webhooks triggers need IFTTT Pro, a paid plan.
Your own script
Gnista JSON is one small object per change, sent as a POST. A Codex session asking to run a command looks like this:
{
"agent": { "id": "codex", "name": "Codex" },
"at": "2026-10-28T14:03:12Z",
"event": "needsYou",
"folder": "/Users/me/Git/shop",
"machine": null,
"message": "Codex wants to run `npm run build`",
"previous": "working",
"project": "shop",
"session": "019a…",
"version": 1
}event is working, needsYou, done, idle or ended, and previous is the state before. Keys and values are fixed English, for scripts, and version goes up if they ever change in a way that breaks them. message is text for people, in the app’s language, so don’t match on it: filter on event, agent.id, project or machine instead. With a secret set, the request carries Authorization: Bearer and your secret.
Without Gnista
- Each agent’s own hooks can post to a URL: Claude Code’s
NotificationandStophooks, Gemini CLI’s and Qwen Code’s hooks, or Codex’snotifyprogram, each runningcurl. They work, but you write and keep them for each agent, and each one sends its own shape of data. - Without hooks, you find out in the agent’s terminal, or from its own notifications on your Mac.
Good to know
- Webhooks are Experimental.
- They only send. To answer a request, use the notch or the agent’s terminal.
- A shortcut runs on your Mac with Gnista JSON as its input, and is stopped after 30 seconds. Test runs it once with
eventset totest. - A Focus, a locked screen and silenced sessions, folders or agents don’t stop them: an automation usually wants everything. Filter at the receiver if you want less.
- Plain
http://works only to your local network, such ashomeassistant.localor an IP address there; anywhere else needshttps://. The first time, macOS may ask whether Gnista can find devices on your local network. - URLs and secrets are kept in your Keychain. Each webhook is sent on its own, with a 10-second timeout and no retries, so a slow one never holds up the others.
- For your phone while you’re away from the Mac: Settings ▸ Notifications ▸ Send to my phone, with Bark, ntfy, Pushover or Telegram. On the Mac itself: Claude Code notifications and Codex notifications.
- Seven days free, then €19 once. More on Claude Code, Codex, Gemini CLI and OpenCode.
More guides.
Claude Code notifications
on your Mac.Know when Claude Code is done or waiting for you, from anywhere on your Mac.
Codex notifications
on your Mac.Know when Codex has finished, or wants to run a command, without watching its terminal.
Approve Claude Code requests
without switching windows.Allow or deny a command or an edit from the notch, then carry on with what you were doing.
Claude Code and Codex limits,
at a glance.Your 5-hour and weekly limits for Claude Code and Codex, under your sessions.
Agents in Xcode,
in your notch.Know when Claude, Codex or Antigravity in Xcode needs you, without keeping Xcode in front.
Agents on a server,
answered from your Mac.Claude Code, Codex and more on a server or another Mac: know when they need you, and answer from your Mac.
Agents in containers,
within reach.Claude Code or Codex in a devcontainer or a Kubernetes pod: their requests still reach your notch.