Get Moshi
push

Push notifications and webhooks

Enable push, copy your API token, test notifications, send custom webhook alerts, and fan out agent pushes across devices on the same license.

updated 3 weeks ago27 min readpage 26 / 32

Moshi supports push notifications from two sources: custom webhooks and agent events from moshi-hook.

Pushed where you'll see itAgent pushes surface on the lock screen, Dynamic Island, and Apple Watch — and you can allow or deny right from the banner.

Enable push

Open Settings -> Push Notifications and turn notifications on. iOS may ask for system permission. If permission is denied, open iOS Settings and enable notifications for Moshi.

After registration succeeds, Moshi shows an API token in the settings screen.

Pause and resume

The notifications switch can pause Moshi delivery without deleting your token. Turn it back on when you want events to resume.

Test notifications

Use the test action in the notification settings screen to send a normal notification or an image notification. Test notifications are unavailable on the iOS simulator.

Webhook API

Use the copied token with Moshi's webhook endpoint:

custom webhook
$curl -X POST https://api.getmoshi.app/api/webhook \
$  -H "Content-Type: application/json" \
$  -d \'{"token":"YOUR_API_TOKEN","title":"Done","message":"Build finished"}'

This is useful from shell scripts, CI jobs, cron tasks, and agent prompts.

Unified push

By default, /api/webhook sends to the device that owns the token. To reach every opted-in device joined to the same Moshi license, include unified: true on the webhook payload.

unified webhook push
$curl -X POST https://api.getmoshi.app/api/webhook \
$  -H "Content-Type: application/json" \
$  -d \'{"token":"YOUR_API_TOKEN","title":"Done","message":"Build finished","unified":true}'

With unified: true, Moshi looks up the license joined by the token's device and fans the push out to every device on that license whose unified-push setting is on. Devices that only restored the store purchase but have not joined the Moshi license are not included.

Events sent by moshi-hook use unified push automatically when the host is attached to a license. The hook cannot choose one specific target device; delivery goes to all opted-in devices on that license. To stop receiving shared host pushes on one device, turn unified push off for that device in Settings -> Your License.

Legacy agent-events endpoint

POST /api/v1/agent-events is a direct-only compatibility endpoint for older third-party harnesses that send structured agent events with a user token. It does not support unified: true; use /api/webhook for custom unified pushes, or /api/v1/hosts/:hostId/events from a paired host daemon.

warn

This legacy endpoint is scheduled for retirement on June 15, 2026. After that date, it returns 410 legacy_agent_events_retired.

Agent notifications

For coding agents, prefer moshi-hook over hand-written webhook prompts. Hooks can distinguish approvals, turn completion, session starts, and tool activity without relying on the agent remembering to call curl.

Images

Webhook payloads can include image data when supported by the endpoint. In the app's test flow, Moshi sends a sample image URL so you can verify rich notification behavior.

Token handling

Treat the API token like a notification secret. Anyone with the token can send notifications to your device. If a token leaks, disable and re-register notifications from the app.