wakehook → your agent#

wakehook is a tiny self-hosted service that watches the user's sleep data (Google Health / Fitbit), detects the moment they woke up, and POSTs the user's agent a neutral user.awake event so the morning routine runs itself — at most once per morning. The agent maps that event into a wake/agent action (its native pattern), so wakehook stays vendor-neutral.

This works with OpenClaw and Hermes Agent — they both ingest a webhook and template it. Everything below is shared except Step 1, where you pick the agent. Work through the steps in order. Ask the user at the decision points instead of assuming. Do not improvise from the README — these steps are verified.

Prerequisites (check, don't assume)#

1. Bun ≥ 1.3 — bun --version; install with curl -fsSL https://bun.sh/install | bash. wakehook is Bun-only ( bun:sqlite); never run it with Node.
2. Google OAuth credentials — a Google Cloud project with the Health API enabled and the googlehealth.sleep.readonly scope, plus an OAuth 2.0 client (client id + secret). An API key will NOT work; sleep data needs user-consented OAuth. Ask the user for the id + secret (reuse their existing Google project if they have one).

Step 1 — wire wakehook to the agent (pick OpenClaw or Hermes)#

wakehook POSTs the raw user.awake event to the agent's inbound webhook; the agent templates it into a wake. Do the subsection for the user's agent — it gives both the agent-side config and the matching wakehook subscriber (drop the subscriber into config.json in Step 3).

Option A — OpenClaw (mapped hook)#

In the OpenClaw gateway config, enable hooks and add a mapping:

json5

{
  hooks: {
    enabled: true,
    path: "/hooks",            // must not be "/"
    token: "<HOOKS_TOKEN>",    // any strong random string
    mappings: [
      {
        match: { path: "wakehook" },   // matches POST /hooks/wakehook
        action: "wake",
        wakeMode: "now",
        name: "wakehook",
        // action "wake" builds its text from textTemplate (NOT messageTemplate —
        // that's only for action "agent"; the wrong one returns HTTP 400):
        textTemplate: "You woke at {{wokeAt}} (slept {{session.durationMin}} min).",
      },
    ],
  },
}

Gateway address: OpenClaw's docs examples use 127.0.0.1:18789 — confirm the user's port. /hooks/* is gated by the token in a header ( Authorization: Bearer or x-openclaw-token). wakehook subscriber:

json

{ "id": "openclaw", "url": "http://<host>:<port>/hooks/wakehook",
  "headers": { "Authorization": "Bearer <HOOKS_TOKEN>" } }

Option B — Hermes Agent (webhook route)#

In the Hermes webhook config, add a route with a prompt template + secret:

yaml

platforms:
  webhook:
    enabled: true
    extra:
      port: 8644
      routes:
        wakehook:
          secret: "<ROUTE_SECRET>"
          prompt: "The user woke at {wokeAt} (slept {session.durationMin} min). Run the morning routine."
          # deliver: telegram   # optional: send the result to a chat

Hermes verifies an HMAC signature; wakehook signs with the route secret under the header Hermes expects. wakehook subscriber:

json

{ "id": "hermes", "url": "http://<host>:8644/webhooks/wakehook",
  "secret": "<ROUTE_SECRET>", "signatureHeader": "X-Webhook-Signature", "signatureFormat": "hex" }

On loopback you can skip signing entirely with Hermes's INSECURE_NO_AUTH and drop secret/ signatureHeader/ signatureFormat.

Step 2 — choose how wakehook gets the sleep data (ask the user)#

Two modes — confirm which they want; don't assume:

• poll (recommended default) — wakehook pulls from Google on a timer. No public URL / tunnel / open port (all outbound). By default it only polls around the morning window and stops once it has fired today ( pollWindowOnly), so a short pollIntervalMs (5 min default) is cheap — wake is detected within one interval. This path is verified end-to-end.
• webhook — Google pushes the instant data lands → fires immediately, but requires a public HTTPS endpoint for wakehook plus registering a Google Health sleep subscription. ⚠️ This path is not yet verified — only choose it if the user explicitly wants instant fires and can expose an endpoint.

If the user has no preference, use poll.

Step 3 — configure wakehook#

Create config.json in the working directory. Set timezone to the user's IANA zone and drop in the subscriber from Step 1 (the OpenClaw or Hermes one):

json

{
  "dbPath": "./wake.sqlite",
  "source": "google-health",
  "inference": {
    "timezone": "Europe/Brussels",
    "windowStart": "04:00",
    "windowEnd": "11:00",
    "minDurationMin": 180,
    "supersedeGapMin": 45
  },
  "google": { "mode": "poll", "pollIntervalMs": 300000, "pollLookbackMin": 720, "pollWindowOnly": true, "pollWindowMarginMin": 30 },
  "subscribers": [
    { "id": "openclaw", "url": "http://<host>:<port>/hooks/wakehook", "headers": { "Authorization": "Bearer <HOOKS_TOKEN>" } }
  ]
}

The subscribers array above uses the OpenClaw entry; swap it for the Hermes entry from Step 1 if that's the agent. You can list both to fan out to multiple agents.

No preset needed — generic (the raw event) is the default and is what both agents' mappings/routes expect. The subscriber's auth (the OpenClaw bearer or the Hermes secret/signature) must match the agent config from Step 1.

If the user chose webhook mode instead: set "google" to { "mode": "webhook", "webhookAuthToken": "<random>" }, also put GOOGLE_WEBHOOK_AUTH_TOKEN in .env, expose wakehook's /webhook over public HTTPS, and register a Google Health sleep subscription pointing at it. (Unverified.)

Create .env (keep secrets out of config.json):

bash

GOOGLE_CLIENT_ID=<client-id>
GOOGLE_CLIENT_SECRET=<client-secret>
GOOGLE_REDIRECT_URI=http://localhost:8080/oauth/callback

Ensure http://localhost:8080/oauth/callback is an authorized redirect URI on the OAuth client.

Step 4 — authorize once#

bash

bunx wakehook-auth

Prints a Google consent URL — give it to the user to open and approve. It stores a refresh token in ./wake.sqlite and auto-refreshes forever (one-time step). If Google returns HTTP 400, the OAuth client is missing the localhost:8080/oauth/callback redirect URI — add it and retry.

Step 5 — run it#

bash

bunx wakehook

(Docker alt: docker run -v wakehook-data:/data --env-file .env ghcr.io/robbeverhelst/wakehook.) Keep it running (long-lived process / service). In poll mode it polls Google every pollIntervalMs around the morning window only (set pollWindowOnly: false to poll all day) and, on the morning wake, POSTs the agent once.

Step 6 — decide what happens on wake (optional)#

By default the Step-1 hook just nudges the agent. To make waking up do something, shape the behavior on the agent side (the OpenClaw mapping or the Hermes route prompt) — not in wakehook. wakehook only supplies the trigger; the actual abilities (calendar, weather, messages, …) come from the agent's own skills/tools — install/enable those separately.

For OpenClaw the lever is the mapping; for Hermes it's the route prompt (and deliver:). OpenClaw mapping examples:

A — simple nudge, routine in the prompt ( action: "wake"): make textTemplate the instruction the main session executes.

json5

{
  match: { path: "wakehook" },
  action: "wake",
  wakeMode: "now",
  textTemplate: "Good morning — the user just woke ({{wokeAt}}). Run the morning routine: review today's calendar, summarize overnight messages, and give the weather.",
}

B — full routine run on a dedicated agent ( action: "agent"): route to an agent that has the relevant skills, and deliver the result to a chat surface.

json5

{
  match: { path: "wakehook" },
  action: "agent",
  agentId: "morning",          // an agent you've set up with calendar/weather/etc. skills
  wakeMode: "now",
  messageTemplate: "User woke at {{wokeAt}} (slept {{session.durationMin}} min). Produce the morning briefing.",
  deliver: true,               // send the result back to a chat surface…
  channel: "last",             // …e.g. Telegram/Discord (defaults to last used)
}

Note: you generally don't trigger a cron from this — wakehook is the real wake signal, so it replaces guessing a fixed time. Just run the task on the event. The capabilities themselves are separate agent skills; this step only wires when and what to ask for.

What the agent receives#

wakehook POSTs the raw, neutral event; the agent's mapping/route templates it:

text

POST http://<host>:<port>/<your-agent-route>
Content-Type: application/json
<auth header per Step 1: Authorization: Bearer …  (OpenClaw)  or  X-Webhook-Signature: …  (Hermes)>

{ "event": "user.awake", "wokeAt": "2026-06-13T08:04:00Z", "user": "self",
  "source": "google-health",
  "session": { "start": "...", "end": "2026-06-13T08:04:00Z", "durationMin": 464 } }

The agent turns this into a now wake with the templated text — handle that as the trigger to run the morning routine. wakehook also sends X-Wake-Event-Id for idempotency. Fires at most once per morning.

Verify without waiting for morning#

bash

curl -X POST http://localhost:8080/test/replay \
  -H 'Content-Type: application/json' -d '{}'

Injects a synthetic wake "now" and delivers it exactly like a real one — confirm the agent maps it and runs the routine.

Gotchas#

• Bun-only — never run with Node.
• Auth must match the agent (else 401): OpenClaw — the Authorization bearer must equal the gateway hooks.token, hooks enabled, and the mapping exists. Hermes — secret must equal the route secret and signatureHeader / signatureFormat must match ( X-Webhook-Signature / hex), with the route defined; or use INSECURE_NO_AUTH on loopback.
• poll needs the OAuth creds but no inbound URL; webhook is instant but unverified — prefer poll unless the user asks otherwise.
• A Google API key is not enough — it needs the OAuth client + wakehook-auth.
• OpenClaw HTTP 400 hook mapping requires text → an action: "wake" mapping must use textTemplate (only action: "agent" uses messageTemplate).
• If the hook returns 200 but nothing happens, check the OpenClaw version (a known issue affected some 2026.3.x builds) and that the mapping action: "wake" is set.

Source + full docs: https://github.com/robbeverhelst/wakehook