PresenceWebhook

A Hammerspoon Spoon that sends a webhook when you become active after being idle.

What is this?

PresenceWebhook notifies external services (Slack, Discord, home automation, etc.) when you return to your computer after being away. Useful for:

• Letting your team know you're back
• Triggering home automation when you sit down to work
• Logging your work patterns

Quickstart

1. Install Hammerspoon: https://www.hammerspoon.org
2. Download the latest PresenceWebhook.spoon zip from Releases: https://github.com/manuel-grondona/presence-webhook-spoon/releases/latest
3. Double-click the zip to unzip it.
4. Double-click PresenceWebhook.spoon to install it. If it does not show up in Hammerspoon, manually copy it into ~/.hammerspoon/Spoons/ (Finder -> Go -> Go to Folder...).
5. Click the Hammerspoon menu bar icon -> Open Config.
6. Paste this into ~/.hammerspoon/init.lua, then save:

hs.loadSpoon("PresenceWebhook")
spoon.PresenceWebhook
  :configure({
    idleThresholdSeconds = 600,
    cooldownSeconds = 600,
    webhookURL = "https://your-service.com/webhook",
    headers = { Authorization = "Bearer YOUR_API_KEY" },
    messageTemplate = "User active after {{idle_seconds}}s at {{timestamp}}",
  })
  :start()

7. Update the webhook URL and API key in the config above.
8. Click the Hammerspoon menu bar icon -> Reload Config.
9. Grant Accessibility permissions to Hammerspoon when prompted.

Example values:

• idleThresholdSeconds = 600 means 10 minutes
• cooldownSeconds = 600 means 10 minutes

Privacy note

This Spoon only detects activity and does not log or record what you type.

Advanced install (SpoonInstall)

If you already use SpoonInstall, you can install from a Releases zip URL:

hs.loadSpoon("SpoonInstall")
spoon.SpoonInstall:installSpoonFromZipURL("https://github.com/manuel-grondona/presence-webhook-spoon/releases/latest/download/PresenceWebhook.spoon.zip")

Then reload Hammerspoon. Docs: https://www.hammerspoon.org/Spoons/SpoonInstall.html

How it works

• Listens for mouse/keyboard events via hs.eventtap.
• If you were idle for idleThresholdSeconds, the next input triggers a webhook.
• Cooldown prevents repeated notifications.

Logs

Log file: ~/.hammerspoon/presence-webhook.log

Configuration

• idleThresholdSeconds (default 600)
• cooldownSeconds (default 600)
• webhookURL (required)
• headers (optional)
• payloadFn (optional override function; receives the base event table with idle_seconds, timestamp, host, event and returns the full payload table)
• messageTemplate (optional string template for message)
• payloadTemplate (optional table of templated values, merged into the payload)
• logPath (optional, defaults to ~/.hammerspoon/presence-webhook.log)

Default payload

{
  "event": "user_active_after_idle",
  "idle_seconds": 3600,
  "timestamp": "2026-01-14T20:10:35Z",
  "host": "My-MacBook"
}

Configuration examples

payloadFn overrides the entire payload. Use it when you want full control:

payloadFn = function(event)
  return {
    message = "Back after " .. event.idle_seconds .. "s",
    metadata = event,
  }
end

messageTemplate adds a message field on top of the default payload:

messageTemplate = "Back after {{idle_seconds}}s at {{timestamp}}"

payloadTemplate adds custom fields (templated strings are rendered):

payloadTemplate = {
  message = "Back after {{idle_seconds}}s",
  metadata = {
    idle_seconds = "{{idle_seconds}}",
    timestamp = "{{timestamp}}",
    host = "{{host}}",
  },
}

Template variables

Use {{...}} placeholders in messageTemplate or payloadTemplate.

Available values:

• idle_seconds
• timestamp
• host
• event

Notes:

• Templates apply only when payloadFn is not set, because payloadFn returns the entire payload.
• payloadTemplate can include nested tables; string values are rendered.

API methods

• spoon.PresenceWebhook:start() – Start listening
• spoon.PresenceWebhook:stop() – Stop listening
• spoon.PresenceWebhook:toggle() – Toggle on/off

Troubleshooting

• If no events fire, make sure Hammerspoon has Accessibility permissions.
• Confirm the log file at ~/.hammerspoon/presence-webhook.log is being written.
• Use the menu bar item to reopen permissions or toggle the listener.

Menu bar

The Spoon shows a menu bar item:

• Toggle enable/disable
• Open log file
• Open permissions settings
• Quit (disables listener)

License

MIT