Webtonative Push Notification API

Send push notifications to your app's users from your own server, and cancel notifications you scheduled earlier.

All URLs in this document are relative to the Webtonative API base URL, written as {BASE_URL}.

Before you start

You need:

1. An organisation API key and secret that have the WEBTONATIVE_NOTIFICATION permission. Create one from your organisation's API key settings in the Webtonative dashboard. The secret is shown only once, so store it safely.
2. Your app's ID (appId). The app must belong to the same organisation as the API key.
3. A plan that includes Webtonative Push. It isn't included on one-time plans. The app's demo or subscription must also still be active.
4. Push set up for each platform you send to:
   • Android: a Firebase project linked in the Webtonative Push addon.
   • iOS: an APNs key added in the Webtonative Push addon. iOS notifications only work once the app has been purchased.

Keep your API secret on your server. Never put it in your website, mobile app or any other client-side code.

Authentication

Send your key and secret in these headers on every request:

1. Send a notification

POST {BASE_URL}/api/v1/public/push-notification/send

Request body

Text fields are trimmed before they are checked.

Sounds

Use one of the custom notification sounds already added to your app's build, referenced by its file name.

"sounds": {
  "android": { "name": "order_ready.mp3" },
  "ios": { "name": "order_ready.wav" }
}

• The name must exactly match a sound added to the app for that platform.
• File names must start with a lowercase letter, contain only lowercase letters, digits and _, and end in .mp3 or .wav.
• Leave out a platform, or set it to null, to use the default system sound.

Audience

Everyone (default when you leave out audience). This sends to every subscribed device on the selected platforms:

"audience": { "type": "EVERYONE" }

Specific users. You describe the users with groups, which is a list of groups where each group is a list of filters:

• A device must match all filters in a group (AND).
• A device only has to match any one group (OR).

"audience": {
  "type": "SPECIFIC",
  "groups": [
    [ { "type": "TAG", "key": "plan", "operator": "IS", "value": "premium" },
      { "type": "LOGIN", "operator": "LOGGED_IN" } ],
    [ { "type": "USER", "field": "EMAIL", "operator": "IS", "value": "jane@example.com" } ]
  ]
}

The example above reaches logged-in users tagged plan = premium, or the user with the email jane@example.com.

Limits: up to 10 groups, and up to 10 filters per group.

Filter types

Examples:

{ "type": "TAG", "key": "city", "operator": "EXISTS" }
{ "type": "USER", "field": "EXTERNAL_USER_ID", "operator": "IS", "value": "user_8812" }
{ "type": "CREATED_AT", "operator": "AFTER", "date": "2026-09-01" }
{ "type": "SESSION", "field": "LAST_SESSION", "operator": "GREATER_THAN", "value": 7, "unit": "DAYS" }
{ "type": "APP_VERSION", "platform": "android", "operator": "IS_NOT", "versions": ["1.0.0", "1.0.1"] }

Examples

Send to everyone now:

curl -X POST "{BASE_URL}/api/v1/public/push-notification/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -d '{
    "appId": "YOUR_APP_ID",
    "title": "Flash sale is live",
    "body": "Up to 50% off for the next 2 hours.",
    "launchUrl": "https://example.com/sale",
    "imageUrl": "https://example.com/images/sale.png"
  }'

Schedule a notification for one user on Android:

curl -X POST "{BASE_URL}/api/v1/public/push-notification/send" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -d '{
    "appId": "YOUR_APP_ID",
    "title": "Your order has shipped",
    "body": "Order #1042 is on its way.",
    "platforms": ["android"],
    "audience": {
      "type": "SPECIFIC",
      "groups": [[{ "type": "USER", "field": "EXTERNAL_USER_ID", "operator": "IS", "value": "user_8812" }]]
    },
    "scheduleType": "SCHEDULED",
    "scheduledAt": "2026-10-20T09:30:00Z"
  }'

Node.js:

const res = await fetch(`${BASE_URL}/api/v1/public/push-notification/send`, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.W2N_API_KEY,
    "x-api-secret": process.env.W2N_API_SECRET,
  },
  body: JSON.stringify({
    appId: process.env.W2N_APP_ID,
    title: "Flash sale is live",
    body: "Up to 50% off for the next 2 hours.",
  }),
})
const data = await res.json()
if (!data.isSuccess) throw new Error(data.error)
console.log(data.notification._id, data.notification.status)

Success response

HTTP 201:

{
  "isSuccess": true,
  "notification": {
    "_id": "6703f1c2a9e4b2d1c8e0f123",
    "appId": "YOUR_APP_ID",
    "source": "API",
    "title": "Flash sale is live",
    "body": "Up to 50% off for the next 2 hours.",
    "launchUrl": "https://example.com/sale",
    "imageUrl": "https://example.com/images/sale.png",
    "platforms": ["android", "ios"],
    "sounds": {},
    "audience": { "type": "EVERYONE", "groups": [] },
    "scheduleType": "IMMEDIATE",
    "scheduledAt": null,
    "status": "SENDING",
    "stats": {
      "targeted": 0,
      "accepted": 0,
      "failed": 0,
      "delivered": 0,
      "opened": 0,
      "errors": []
    },
    "createdAt": "2026-10-08T10:15:30.000Z",
    "updatedAt": "2026-10-08T10:15:30.000Z"
  }
}

Save notification._id. You need it to cancel a scheduled notification.

notification.status tells you what happened:

Once delivery is finished, the notification moves to SENT, FAILED or NO_RECIPIENTS. You can see the final status and delivery stats in the Webtonative dashboard.

Error responses

Validation errors are returned with HTTP 201 and isSuccess: false, so always check isSuccess:

{ "isSuccess": false, "error": "Add a title and a message before sending" }

App access errors come back with an HTTP error status:

Rate limit

Send calls are limited per app, in 15-minute windows. A window starts at the first call and lasts 15 minutes.

limit per window = max(subscribed devices × 10, 100)

So an app with 5 subscribers can make 100 calls per window, and an app with 2,000 subscribers can make 20,000. The limit is worked out once at the start of each window. Every send call counts towards it, including calls that fail validation.

Each send response includes these headers:

When you go over the limit, you get HTTP 429 with a Retry-After header (in seconds):

{
  "isSuccess": false,
  "errorCode": "RATE_LIMIT_EXCEEDED",
  "error": "Rate limit of 100 requests per 15 minutes exceeded. Try again in 412 seconds.",
  "retryAfter": 412
}

Tip: Don't make one call per user. One call with an audience filter (for example a TAG filter) reaches many users at once.

2. Cancel a scheduled notification

POST {BASE_URL}/api/v1/public/push-notification/{id}/cancel

This cancels a notification whose status is SCHEDULED. Notifications that are already sending, sent or saved as drafts can't be cancelled.

Path parameter

Request body

Example

curl -X POST "{BASE_URL}/api/v1/public/push-notification/6703f1c2a9e4b2d1c8e0f123/cancel" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -d '{ "appId": "YOUR_APP_ID" }'

Success response

HTTP 201:

{ "isSuccess": true }

Error responses

All of these come back with HTTP 201 and isSuccess: false:

The cancel endpoint isn't rate limited.

Handling responses

1. Check the HTTP status. 401 and 403 mean an authentication or app access problem, and 429 means you hit the rate limit (wait for Retry-After seconds).
2. Check isSuccess. If it's false, the request was rejected and error says why.
3. If it's true, keep notification._id and notification.status from the send response.