Critical notifications

Every notification has one of five priorities. Set it with priority, or let it default to the Source’s own.

Priority	What it does
silent	Goes to the inbox without a notification on screen.
quiet	Shows a notification with no sound.
normal	A standard notification. Arrives silently during quiet hours.
important	Time Sensitive: it can break through a Focus.
critical	Repeats until it is acknowledged, canceled or expires.

Send a Critical notification

curl https://api.pocketbell.dev/v1/messages \
  -H "Authorization: Bearer pb_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: api-2-down-2026-09-28T02:14" \
  -d '{"title": "api-2 is down", "message": "Health check failed 3 times",
       "priority": "critical", "retry": 300, "expire": 3600}'

• retry is the time between repeats, in seconds: 30 to 3600, 300 by default.
• expire is when repeats stop, in seconds from now: 60 to 10800, 3600 by default.

Each repeat plays the Source’s Critical sound. Anyone on the account can Acknowledge it from the notification itself, or from the app, and the repeats stop on every device.

Check on it

The response carries the notification’s id. Ask for it with the same key:

curl https://api.pocketbell.dev/v1/messages/msg_… \
  -H "Authorization: Bearer pb_live_…"

status is awaiting_acknowledgment, acknowledged, canceled or expired, with acknowledged_at and acknowledged_device once someone responds. /v1/messages/{id}/deliveries lists each device it went to, and when each one reported it delivered.

Cancel it when the problem clears

curl -X POST https://api.pocketbell.dev/v1/messages/msg_…/cancel \
  -H "Authorization: Bearer pb_live_…"

Callbacks (Pro)

Add "callback": "https://…" and Pocketbell POSTs to it when the notification is acknowledged, or when it expires unacknowledged:

{
  "type": "message.acknowledged",
  "timestamp": "2026-09-28T02:21:07Z",
  "data": {
    "id": "msg_…",
    "source_id": "src_…",
    "created_at": "2026-09-28T02:14:00Z",
    "acknowledged_at": "2026-09-28T02:21:06Z"
  }
}

The type is message.acknowledged or message.expired. Callbacks are signed to the Standard Webhooks spec, with the webhook-id, webhook-timestamp and webhook-signature headers, so any Standard Webhooks library can verify them. The Source’s signing secret (whsec_…) is in the app, under the Source.

A callback that fails is retried. Addresses that resolve to a private, loopback or link-local network are refused.