API Reference

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 your device secret (sends to one device), your user secret (sends to all devices on your account), or a named webhook secret (a custom-labelled URL you create).

Request formats

Plain text — the entire body becomes the notification message:

curl -X POST https://api.notifikations.com/api/v1/YOUR_SECRET \
  -d 'Deploy succeeded ✅'

JSON — full control over all fields:

curl -X POST https://api.notifikations.com/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://api.notifikations.com/api/v1/YOUR_SECRET?message=Hello&title=Alert"

Payload fields

Available sounds

Response

Scheduled delivery

Add a send_at field to any notification request to deliver it at a future time. The server stores the job and fires it automatically — your script or service does not need to stay running.

curl -X POST https://api.notifikations.com/api/v1/YOUR_SECRET \
  -H 'Content-Type: application/json' \
  -d '{"message":"Time to stand up","title":"Reminder","send_at":"2026-04-01T09:00:00.000Z"}'

GET requests also support it:

curl "https://api.notifikations.com/api/v1/YOUR_SECRET?message=Hello&send_at=2026-04-01T09:00:00.000Z"

Scheduled response

{ "success": true, "scheduled": true, "jobId": "uuid", "sendAt": "2026-04-01T09:00:00.000Z" }

Limits & notes

• send_at must be a future ISO 8601 timestamp, within 30 days from now.
• Maximum 10 pending scheduled jobs per webhook URL.
• Delivery precision is approximately ±1 minute (Cloudflare Cron resolution).
• Pro/trial status is evaluated at fire time, not at scheduling time.
• Scheduled notification content is stored on Cloudflare's infrastructure until sent, then deleted immediately. See the privacy policy.

Scheduled response codes

Named webhooks

By default your device secret and user secret are your webhook URLs. Named webhooks let you create additional, independently-labelled URLs — useful when you want separate endpoints for different tools or contexts ("CI", "Server", "Home automation") without sharing the same secret across all of them.

Create a named webhook

POST  /api/v1/webhooks

Generate a new secret locally (e.g. ntf_ci_…), hash it with SHA-256, and register the digest:

curl -X POST https://api.notifikations.com/api/v1/webhooks \
  -H 'Content-Type: application/json' \
  -d '{"deviceDigest":"<sha256(deviceSecret)>","deviceToken":"<apnsToken>","webhookDigest":"<sha256(newSecret)>","label":"CI","scope":"device"}'

On success: {"success":true}. The new webhook URL is then https://api.notifikations.com/api/v1/YOUR_NEW_SECRET and behaves exactly like your regular webhook.

List named webhooks

GET   /api/v1/webhooks?deviceDigest=<digest>&deviceToken=<token>

Returns all named webhooks registered to a device:

{
  "webhooks": [
    { "webhookDigest": "abc…", "label": "CI", "scope": "device", "createdAt": "2026-03-30T…" },
    { "webhookDigest": "def…", "label": "Home", "scope": "user",   "createdAt": "2026-03-30T…" }
  ]
}

Delete a named webhook

DELETE /api/v1/webhooks/:webhookDigest

curl -X DELETE https://api.notifikations.com/api/v1/webhooks/<webhookDigest> \
  -H 'Content-Type: application/json' \
  -d '{"deviceDigest":"<sha256(deviceSecret)>","deviceToken":"<apnsToken>"}'

Immediately invalidates the URL. The raw secret you generated was never stored, so there is nothing else to revoke.

Limits & notes

• Maximum 10 named webhooks per device.
• Each named webhook has its own independent secret — rotating your device or user secret does not affect them.
• Deleting or unregistering a device automatically deletes all named webhooks owned by that device.
• Named webhook URLs support all the same payload fields and scheduled delivery as regular webhooks.
• Pro/trial status is checked at send time against the owner device.

Interactive actions

Add a category field to show tappable action buttons on the notification. When the user taps a button, the app POSTs the result to your callback_url — no server round-trip, no stored state.

Categories

Buttons run in the background — the app does not need to open for the callback to fire.

Example — deployment approval

curl -X POST https://api.notifikations.com/api/v1/YOUR_SECRET \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Deployment",
    "message": "Deploy to production?",
    "category": "YES_NO",
    "callback_url": "https://your-n8n.com/webhook/abc123"
  }'

When the user taps Yes, the app sends:

POST https://your-n8n.com/webhook/abc123
Content-Type: application/json

{ "action": "yes" }

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.

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.

Unregister a device

DELETE /api/v1/unregister