Notifications

Notifications are immutable send requests with a content snapshot, audience snapshot, delivery options, and recipient results. Create one through the dashboard or POST /v1/notifications.

Minimal send#

Every creation request needs title, body, target, and a unique Idempotency-Key header. A template may supply the title and body.

curl --request POST https://api.honeynotify.com/v1/notifications \
  --header "Authorization: Bearer $HONEYNOTIFY_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: welcome-customer-123-v1" \
  --data '{
    "title": "Welcome to the hive",
    "body": "Your account is ready.",
    "target": {"type": "user", "external_user_id": "customer_123"}
  }'

Targets#

For compound inclusion and exclusion rules, see Segments and targeting.

Content fields#

Custom data should be small and contain only values your clients need. Push providers impose their own payload limits, so avoid embedding documents or binary content.

Delivery controls#

priority and interruption_level are independent. Priority controls HoneyNotify's processing queue; interruption level controls device presentation. Existing requests that omit interruption_level retain their current provider transport behaviour and are reported as active.

Apple Critical Alerts work only when Apple has approved the app's Critical Alerts entitlement and the user has granted critical-alert permission. Without both, selecting critical cannot guarantee mute or Focus bypass. Android has no direct equivalent: HoneyNotify uses its strongest generally permitted urgent channel, but users remain in control of channel sound, importance, and Do Not Disturb behaviour. HoneyNotify does not request full-screen intent or DND-policy access.

Platform references: Apple remote notification payloads, Apple Critical Alerts entitlement, and Android notification channels.

Example with interaction and expiry:

{
  "title": "Price drop",
  "body": "An item you saved is now £24.",
  "target": {"type": "segment", "segment_id": "a7f7b391-15e8-47b9-a123-f1bea3994a82"},
  "interruption_level": "time_sensitive",
  "click_url": "myapp://saved-items",
  "ttl": 21600,
  "collapse_id": "saved-item-price-drop",
  "actions": [
    {"id": "view", "text": "View item"},
    {"id": "dismiss", "text": "Not now"}
  ]
}

Scheduling and local delivery#

Use scheduled_at for one absolute moment. Use local_delivery_time when each device should receive the notification at a wall-clock time in its own timezone. Keep device and user timezone data current; missing or invalid profile data cannot produce accurate local-time delivery.

A future scheduled notification is returned with status: "draft". When due, it is moved to the queue. An immediate or past-dated notification is returned as queued.

Idempotency#

The Idempotency-Key is mandatory and scoped to the app. If a connection fails after sending, retry the identical request with the identical key. HoneyNotify returns the original ID and adds idempotent_replay: true.

{
  "notification_id": "b39ddcd7-2892-4c3d-8145-0ce3bc9e3ec4",
  "status": "queued",
  "interruption_level": "active",
  "idempotent_replay": true
}

Generate keys from a durable business event where possible—for example, invoice-4831-overdue-v2—so application restarts cannot accidentally duplicate a send.

Read status and results#

GET /v1/notifications?page=1&limit=50
GET /v1/notifications/{notification_id}
GET /v1/notifications/{notification_id}/recipients?page=1&limit=50
GET /v1/notifications/{notification_id}/events?page=1&limit=50

The notification summary includes recipient, accepted, and failed counts. Recipient rows contain the device ID, external user ID, status, attempt count, last error, and last update time. Event rows contain event type, source, properties, and occurrence time.

accepted is a provider acknowledgement. For observable device lifecycle, use SDK events such as received, confirmed_delivered, and opened.

Cancel a notification#

POST /v1/notifications/{notification_id}/cancel

Cancellation is available while a notification is draft, queued, or processing. It prevents work that has not yet been handed to a provider; it cannot recall a push already accepted by APNs, FCM, or Web Push. A notification that is already terminal returns a validation error.