# Send an update

Send a useful message, file it into the inbox, and give the recipient a clear next step. Webhook and terminal examples below describe the same package-pickup workflow.

HTML: https://notify.belweave.ai/docs/send-update

## Send from a webhook

For a package-pickup alert, send a JSON object with `body`. The service supplies the sender title and other defaults. This example uses a placeholder token; substitute the URL saved during [connection setup](https://notify.belweave.ai/docs/quickstart#webhook-url).

```bash
curl -X POST https://notify.belweave.ai/hooks/whk_your_token -H 'Content-Type: application/json' -d '{"body":"Package PKG-42 is ready at the front desk."}'
```

## Send from a terminal

Use `notify send <body>` for an update from a terminal. It targets active supported devices unless you specify routing. Set the sender title per call; sends with the same title are threaded together.

```bash
notify send "Package PKG-42 is ready" \
  --title "Warehouse desk" \
  --image https://warehouse.example.com/icon.png \
  --url https://warehouse.example.com/packages/PKG-42
```

| Flag | Type | Description |
| --- | --- | --- |
| `--title` | string | Sender name. Defaults to `Notify`. |
| `--image` | url | Public HTTPS avatar, same rules as the webhook `imageUrl`. |
| `--url` | url | Web URL, app deep link, or Shortcuts URL opened when tapped. |
| `--device` | id, repeatable | Target eligible devices by stable ID. Included for free. |
| `--project` | string | File the notification into a named project in the Notify app inbox. |
| `--summary` | string | Short push/preview text for a long body. Bodies can hold up to 8,000 characters. |
| `--markdown` | boolean | Record the body as Markdown (same as `--body-format markdown`); V1 renders plain text. |
| `--app` | app id | Open this [web app](https://notify.belweave.ai/docs#web-apps) in Notify when tapped; `--url` must stay on its origin. |
| `--idempotency-key` | string | Safe retries: replays return the original result without a second push. |
| `--stdin` | boolean | Merge a JSON object from stdin under the explicit flags. |

> A connection’s sends use the same rate/usage accounting as webhook sends: a requester window and an account-wide window. Notifications have no monthly cap.

## Organize longer messages

Use `project` to keep recurring updates together, for example Warehouse maintenance. Names are matched within an account after Unicode normalization and case folding: `Warehouse maintenance` and `warehouse maintenance` resolve to one project, with the first spelling kept for display. Unfiled messages appear under Other.

Put the full report in `body` and a short actionable digest in `summary`. The digest supplies banners and list previews; the complete body remains in the inbox detail. Clients currently show plain text and tappable links. `bodyFormat: "markdown"` stores the format metadata but does not enable Markdown rendering in V1.

> The account limit is 500 projects. A send that introduces a name beyond this limit can still create the notification, unfiled, with a `message` explaining the fallback. Existing names continue to resolve.

## Give the tap a destination

A destination belongs in `url`, either on the service or in the individual send. The recipient must tap to open it. A received push alone cannot launch a site, another app, or a shortcut.

- Prefer a universal `https://` link when the destination supports app and browser routes. On iOS, an installed associated app can handle it; otherwise the website opens.
- A documented custom scheme can address an installed app directly, such as `warehouse://packages/PKG-42`. Without a handler, the destination cannot open.
- URL-encode spaces and reserved characters in route names and query values. Shortcuts are an iOS-specific destination.

```json
{
  "body": "Package PKG-42 is ready for collection.",
  "url": "warehouse://packages/PKG-42"
}
```

For an iPhone shortcut, follow Apple’s [run-shortcut URL format](https://support.apple.com/guide/shortcuts/run-a-shortcut-from-a-url-apd624386f42/ios). Match the saved shortcut’s name and encode its query values. `input=text` passes the `text` value; `input=clipboard` uses the device clipboard.

```json
{
  "body": "Warehouse pickuped. Tap to run the follow-up.",
  "url": "shortcuts://run-shortcut?name=Package%20Pickup&input=text&text=collect%20PKG-42"
}
```

> The device may ask the person to unlock or grant shortcut permissions. Notify cannot run a shortcut merely because a notification arrived. The server rejects executable or local schemes including `javascript:`, `data:`, `file:`, `blob:`, and `about:`.