API Reference

All endpoints are at https://ntf-worker.buzagloidan.workers.dev

Send a notification

This is the main webhook endpoint. The secret in the URL acts as the credential — no additional headers required.

POST  /api/v1/:secret
GET   /api/v1/:secret?message=Hello

The :secret can be either your device secret (sends to one device) or your user secret (sends to all devices on your account).

Request formats

Plain text — the entire body becomes the notification message:

curl -X POST https://ntf-worker.buzagloidan.workers.dev/api/v1/YOUR_SECRET \
  -d 'Deploy succeeded ✅'

JSON — full control over all fields:

curl -X POST https://ntf-worker.buzagloidan.workers.dev/api/v1/YOUR_SECRET \
  -H 'Content-Type: application/json' \
  -d '{"message":"Tests passed","title":"CI","sound":"cha_ching"}'

GET — useful for webhooks that only support GET:

curl "https://ntf-worker.buzagloidan.workers.dev/api/v1/YOUR_SECRET?message=Hello&title=Alert"

Payload fields

Field	Type	Description
`message`	string required	The notification body text.
`title`	string	Bold title shown above the message.
`subtitle`	string	Secondary line below the title.
`sound`	string	`default`, `none`, or a custom sound name (see below).
`open_url`	string	URL opened when the notification is tapped.
`image_url`	string	Remote image displayed in the notification.
`interruption-level`	string	`passive`, `active`, or `time-sensitive`.
`filter-criteria`	string	iOS Focus filter matching value.
`expiration_date`	ISO 8601	Deadline after which APNs discards the notification.

Available sounds

default · brrr · bell_ringing · bubble_ding · cha_ching · cat_meow · dog_barking · door_bell · duck_quack · upbeat_bells

Response

Status	Body	Meaning
`200`	`{"success":true,"apnsId":"…"}`	Notification accepted by APNs.
`200`	`{"success":true,"sent":2,"failures":0}`	User secret fan-out result.
`400`	`{"error":"message is required"}`	Missing required field.
`404`	`{"error":"webhook not found"}`	Secret not registered.
`502`	`{"error":"…"}`	APNs rejected the notification.

Register a device

POST  /api/v1/register

Called automatically by the iOS app on first launch and when the APNs token changes. Not intended for direct use.

Field	Type	Description
`deviceToken`	string required	Hex-encoded APNs device token.
`deviceDigest`	string required	SHA-256 hex digest of the device secret.
`userDigest`	string required	SHA-256 hex digest of the user secret.
`label`	string	Human-readable device name.

Rotate secrets

POST  /api/v1/rotate

Generates a new device webhook URL and immediately invalidates the old one. Called by the app — not intended for direct use.

Field	Type
`oldDigest`	string required
`newDigest`	string required
`deviceToken`	string required

Unregister a device

DELETE /api/v1/unregister

Field	Type
`deviceDigest`	string required