Webhooks to iPhone notifications

Anything that can send an HTTP request can notify your phone: CI jobs, coding agents, cron scripts, monitors. Each service carries its own name, avatar, and tap destination, and Hark fills in any field you omit from those service defaults.

There are two APIs, both authenticated by the same webhook token. The Notification API sends one-shot pushes and optional approval prompts. The Activity API drives a stateful Live Activity on the Lock Screen and in the Dynamic Island.

1. Sign in at hark.ryan.ceo.
2. Register your iPhone with the Hark app.
3. Create a service in the dashboard and give it a title, avatar, and tap URL.
4. Copy the secret webhook URL it returns.

The plaintext token is shown when the service is created and whenever you rotate it. Treat it as a credential: anyone holding it can notify your devices.

An unknown or rotated token returns 404 with { "ok": false, "error": "Unknown webhook" }.

Only body is required. Everything else falls back to the service defaults.

curl -X POST https://hark.ryan.ceo/hooks/whk_your_token \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: deploy-184-production' \
  -d '{
    "body": "Production deployed successfully.",
    "title": "GitHub",
    "imageUrl": "https://github.com/github.png",
    "url": "https://github.com/acme/app/actions"
  }'

{
  "ok": true,
  "eventId": "evt_Cxns2IdbF4H0TJYq",
  "delivered": 1
}

eventId identifies the event in the dashboard activity log and, for interactive notifications, is the handle used to read or cancel the pending response. delivered is the number of push requests accepted by Expo.

A request with no registered device still succeeds with delivered: 0 and a message field, so an unpaired phone never fails your build.

Send Content-Type: application/json. An unrecognised token returns 404; a payload that fails validation returns 400 with an issues array describing each field.

Send an optional Idempotency-Key header of 1 to 200 characters. Keys are scoped to a single service.

• Same key and payload: the original event is returned with idempotent: true.
• Same key while the first request is still in flight: 202 Accepted.
• Same key with a different payload: 409 Conflict.
• Blank or over-length key: 400.

By default a request fans out to every active iOS device on the account, most recently seen first. Free accounts are capped at one device, so extra phones are ignored until you upgrade.

Hark Pro can pass a non-empty deviceIds array to target specific iPhones. Copy the stable device IDs from the dashboard. IDs that do not belong to the account return 400 Invalid device selection; owned but inactive or non-iOS devices in the list are skipped silently.

{
  "body": "The production deploy needs attention.",
  "deviceIds": ["dev_your_iphone_id"]
}

Sending deviceIds without device routing on your plan returns 402.

The per-minute counters use a rolling 60-second window and are shared across notifications, interactive responses, and Live Activity operations. A limited request returns 429 with a Retry-After: 60 header and retryAfterSeconds in the body. Exhausting the monthly allowance also returns 429, without a retry hint.

{
  "ok": true,
  "eventId": "evt_Cxns2IdbF4H0TJYq",
  "delivered": 1
}

Provider errors can embed a device push token, so they are recorded in the dashboard activity log rather than returned to the caller. Use that log to find devices that are no longer registered.

Hark Pro can attach a fixed response type to any notification. Supported types are approval (Approve or Deny), yes_no (Yes or No), and text (a short free-form reply).

{
  "title": "Production deploy",
  "body": "Deploy commit 8e7fc2a?",
  "response": {
    "type": "approval",
    "expiresInSeconds": 900,
    "correlationId": "deploy-184",
    "callback": {
      "url": "https://ci.example.com/hark-response",
      "token": "private-callback-token"
    }
  }
}

The response body gains a response object alongside the usual fields:

{
  "ok": true,
  "eventId": "evt_Cxns2IdbF4H0TJYq",
  "delivered": 1,
  "response": { "status": "pending", "expiresAt": "2026-07-25T18:19:04.000Z" }
}

Poll the event with the eventId from the send response, or withdraw it while it is still pending.

curl https://hark.ryan.ceo/hooks/whk_your_token/events/evt_Cxns2IdbF4H0TJYq

curl -X POST https://hark.ryan.ceo/hooks/whk_your_token/events/evt_Cxns2IdbF4H0TJYq/cancel

{
  "ok": true,
  "event": {
    "id": "evt_Cxns2IdbF4H0TJYq",
    "response": {
      "status": "approved",
      "action": "approve",
      "text": null,
      "correlationId": "deploy-184",
      "respondedAt": "2026-07-25T18:06:52.000Z",
      "expiresAt": "2026-07-25T18:19:04.000Z"
    }
  }
}

• status is one of pending, approved, denied, yes, no, replied, expired, or canceled.
• For text prompts, action becomes reply and text holds the answer. For the other types action holds the chosen option and text is null.
• Reading a pending request after expiresAt settles it as expired.
• Cancel returns 404 if the response is not pending, and events belonging to another service are never visible.

When a callback is configured, Hark POSTs the answer to your URL with Authorization: Bearer <callback.token>, Content-Type: application/json, and a Hark-Callbacks/1 user agent. Redirects are not followed and the request times out after 10 seconds.

{
  "type": "notification.response",
  "eventId": "evt_Cxns2IdbF4H0TJYq",
  "correlationId": "deploy-184",
  "kind": "approval",
  "status": "approved",
  "action": "approve",
  "text": null,
  "respondedAt": "2026-07-25T18:06:52.000Z"
}

kind is approval, yes_no, or reply — a text request arrives as reply.

Any response outside the 2xx range is a failure. Hark makes up to five attempts: once immediately, then after 30 seconds, 2 minutes, 10 minutes, and 1 hour. After the last attempt the callback is marked failed and is not retried, so treat the callback as at-least-once and key your handler on eventId.

Callbacks fire only when someone actually answers. Prompts that expire or are canceled never call back — poll the event route if you need to observe those outcomes.

Only title and status are required.

curl -X POST https://hark.ryan.ceo/hooks/whk_your_token/live-activities \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: deploy-184-start' \
  -d '{
    "title": "Deploy #184",
    "status": "Building",
    "progress": 0,
    "symbol": "build",
    "accentColor": "#FF9F0A"
  }'

{
  "ok": true,
  "activityId": "act_9Rk2wQpLm4Tz",
  "sequence": 0,
  "status": "active",
  "accepted": 1,
  "failed": 0,
  "state": { "title": "Deploy #184", "status": "Building", "progress": 0, "symbol": "build" },
  "expiresAt": "2026-07-26T02:04:11.000Z",
  "staleAt": "2026-07-25T22:04:11.000Z",
  "endedAt": null
}

Use activityId in the update and end routes. If you pass your own key when starting, that value works in the URL too, so a script can address its activity without storing the generated ID. Idempotency-Key works on all three write routes and is scoped to the service: a replay returns idempotent: true, and reusing a key with a different payload returns 409.

Live Activities need a device running a Hark build that has registered a push-to-start token. If no device qualifies, the start still returns 201 with accepted: 0 and an explanatory message.

PATCH merges into the current state, so send only what changed. At least one field other than ifSequence is required. Each accepted update increments sequence.

curl -X PATCH https://hark.ryan.ceo/hooks/whk_your_token/live-activities/act_9Rk2wQpLm4Tz \
  -H 'Content-Type: application/json' \
  -d '{ "status": "Testing", "progress": 0.6, "accentColor": "#64D2FF" }'

• Pass null for detail or progress to clear the field.
• Pass ifSequence to make the write conditional. A mismatch returns 409 Sequence conflict along with the current state so you can reconcile.
• Updating an activity that has already ended or expired returns 409 Live Activity is already terminal.

curl -X POST https://hark.ryan.ceo/hooks/whk_your_token/live-activities/act_9Rk2wQpLm4Tz/end \
  -H 'Content-Type: application/json' \
  -d '{ "status": "Deployed", "progress": 1, "symbol": "success" }'

The body is optional. dismissAfterSeconds (0 to 14,400, default 0) controls how long the finished card lingers on the Lock Screen before iOS removes it.

status and symbol have defaults on this route, so omitting them overwrites the live values with "Complete" and success. Send them explicitly if you want the final card to read differently.

The five layouts, rendered with the same state:

expiresInSeconds accepts 60 to 28,800 and defaults to 28,800 — eight hours. Once an activity passes its expiry it is marked expired and stops accepting updates.

staleAfterSeconds accepts 0 to 28,800 and defaults to 14,400 — four hours. Past that deadline iOS treats the content as possibly out of date, but the card stays visible and updateable. Every update rolls the deadline forward from now, clamped to the expiry. An update that omits staleAfterSeconds reuses the previous window.

A device can host one Hark Live Activity at a time. Starting another while one is still live on a target device returns 409:

{
  "ok": false,
  "error": "A Live Activity is already active on a target device",
  "code": "ACTIVE_ACTIVITY_CONFLICT",
  "activityId": "act_9Rk2wQpLm4Tz"
}

The activityId is included only when the blocking activity belongs to the same service, so you can update it instead of starting over. Branch on code rather than the message text.

To take the slot instead, pass replace: true in the start payload. Hark silently ends whatever occupies each target device — the old card is dismissed immediately, showing its last state — and then starts your activity. The success response reports how many activities were displaced as replaced; with nothing to displace the start behaves normally and replaced is 0.

replace also displaces activities started by your other services or API tokens, so a stale card from another integration cannot deadlock a device, though a foreign activityId is never disclosed. When the start carries a key, your live activity holding that key is ended everywhere — even on devices the start does not target — so the key always transfers to the new run. The implicit ends are not billed against your notification allowance. Combined with reusable keys this makes key plus replace: true a fixed-key restart you can send on every run.

A start carries an alert, so it may notify the user like a normal notification. Updates and ends carry no alert and are silent. Hark sends every Live Activity push at high APNs priority, which affects delivery speed only, not sound or haptics.

Live Activity operations count against the same per-minute and monthly limits as notifications, so a chatty progress loop consumes the same budget. Throttle to meaningful state changes.

iOS also budgets push-to-start deliveries per app. Rapid successive starts to the same device can be silently suppressed: the start still reports accepted, but the device never registers an update token, so every later update and end fails with MissingUpdateToken. Space fresh starts out by a minute or so — or keep one activity alive and update it, which is cheaper and never hits the budget.

Run it straight from npm with npx harkctl, or install it globally with npm install -g harkctl. Signing in uses a browser device-authorization flow — no tokens on the command line, ever.

npx harkctl auth login

1. The CLI prints a short code and opens hark.ryan.ceo in your browser.
2. Sign in and approve the requested scopes; every scope is shown before you approve.
3. Credentials are written to an OS config file with mode 0600, and the CLI polls until the approval lands.

Each login appears under your dashboard's Services list as an agent connection, with its scopes, creation date, and last use. Revoking it there signs that agent out immediately. harkctl auth status shows the active connection; harkctl auth logout revokes and removes local credentials.

Use repeatable --scope flags to narrow access, --client-name to label the connection, and --expires-in (default 90d) to bound its lifetime. For CI or self-hosted setups, HARK_TOKEN and HARK_API_URL environment variables override the config file.

harkctl services create creates a persistent webhook endpoint for another tool or workflow. Its title, image, and tap URL become defaults, so the sender only needs to POST a body. The command prints the credential-bearing webhookUrl in its JSON response.

harkctl services create \
  --title "Release bot" \
  --image https://example.com/bot.png \
  --url https://ci.example.com/releases

{
  "service": {
    "id": "svc_...",
    "title": "Release bot",
    "imageUrl": "https://example.com/bot.png"
  },
  "webhookUrl": "https://hark.ryan.ceo/hooks/hook_..."
}

Use --stdin to provide the same fields as JSON. services list lists existing services without emitting their webhook credentials. Creation requires services:write; if your CLI login predates that scope, sign in again and approve the updated permissions.

Treat webhookUrl as a secret. Anyone who has it can send notifications through that service.

harkctl notify <body> sends a one-shot push to every active iPhone on your account. Appearance is per call — the title acts as the sender name, and messages with the same title thread together like a service.

harkctl notify "Build 48 passed" \
  --title "CI" \
  --image https://github.com/github.png \
  --url https://ci.example.com/builds/48

Sends from one connection share the webhook per-minute budgets — the requester counts like a service, the account window spans everything — and the same monthly notification allowance.

harkctl notify ask <prompt> sends a push that elicits an answer. Pass exactly one response type: --approval (Approve/Deny), --yes-no (Yes/No), or --text (a short typed reply). The appearance flags from notify all apply.

harkctl notify ask "Deploy 8e7fc2a to production?" \
  --approval --title "Deploybot" --wait --timeout 15m

--wait blocks until the answer arrives or the timeout passes. --poll waits at most 20 seconds to catch an instant answer, for the case where someone is already looking at their phone. A timed-out poll or wait does not end the prompt — it stays answerable until it expires (default 15 minutes, --expires-in to change), and harkctl interaction wait <id> resumes waiting any time.

{
  "interaction": {
    "id": "int_7MFuml-SqoUmpPLo",
    "kind": "reply",
    "status": "replied",
    "response": "ship it",
    "respondedAt": "2026-07-26T11:54:17.927Z"
  },
  "accepted": 1,
  "timedOut": false
}

The activity commands drive the Activity API end to end. Address an activity by the returned ID or by your own --key, and pick a layout with --style.

harkctl activity start --key deploy --replace --style ring \
  --title "Deploy #184" --status "Building" --progress 0.1

harkctl activity update deploy --status "Testing" --progress 0.6 --if-sequence 0

harkctl activity end deploy --status "Shipped" --progress 1 --dismiss-after 45s

• --replace takes the device slot and the key, ending whatever blocks them, so a fixed-key start works on every run.
• --if-sequence rejects stale writes: the update only applies if the activity is still at that sequence.
• --style selects standard, ring, hero, terminal, or steps, and can change mid-flight on update.
• activity get <id|key> reads current state; activity list shows recent activities.

Every successful command prints exactly one JSON object to stdout; diagnostics go to stderr. Exit codes make answers branchable without parsing:

• 0 — success, approved, yes, or replied
• 4 — timed out, canceled, or expired
• 5 — denied or no
• 7 — no device accepted the push
• 1 API error · 2 usage error · 3 authentication or scope error · 6 network error

if harkctl notify ask "Deploy to production?" --approval --wait --timeout 10m; then
  ./deploy.sh && harkctl notify "Deployed" --title "Deploybot"
else
  echo "Not approved" >&2
fi