Push Notifications reference: Server API

As a pub-sub system, our Push Notifications system has two APIs: one for publishing and another for subscribing. Publishing is done via the Server API. The Server API is a RESTful HTTP API. This page describes that API and how you can interact with it to send push notifications.

Note: For a gentler introduction to sending push notifications, see pushing to iOS or pushing to Android.

Note: This page is primarily aimed at developers writing new server libraries for new languages. If possible, you should use one of our official libraries, which are available in several popular server-side languages. See server libraries for iOS or server libraries for Android.

The server API is intended to be used directly by your servers (often via Pusher server libraries such as pusher-http-php). It is therefore intended to be exposed to the world.

The server API is principally used for publishing notifications to interests.

When you push a native notification to an interest, you must prove that you have control of the Pusher app owning that interest. For this, we use the same authentication scheme used for publishing to channels. This scheme uses possession of an app secret as proof, because the app secrets can only be accessed on the dashboard by users with permission to control the app. You prove possession of a secret by using it to sign each HTTP request made to the API, attaching the signature as a query parameter auth_signature.

Endpoint

This document describes the Server API with reference to an HTTP endpoint. The hosted version of our Server API is at the following endpoint:

https://nativepush-cluster1.pusher.com/server_api

Resource: /v1/apps/:pusher_app_id/notifications

Represents the set of all notifications sent on the app with id :pusher_app_id. Each notification has the following JSON representation:

{
  "interests": [InterestString],
  "webhook_url": WebhookURL,
  "webhook_level": WebhookLevel,
  "apns": ApnsPayload,
  "gcm": GcmPayload,
  "fcm": FcmPayload
}

This payload will publish the given notification to all the clients subscribed to the specified interest, on all supported platforms.

The interest array length must be exactly 1.

Each interest name can be up to 164 characters. Each character in the name must be an ASCII upper- or lower-case letter, a number, or one of _=@,.;. Note that the hyphen (-) is not a valid character in interest names. This character is reserved for the possibility in future of marking interest names with prefixes (such as private- or presence-).

The WebhookLevel must be either "INFO" (errors-only) or "DEBUG" (everything). If omitted, it defaults to "INFO".

For the ApnsPayload format, see Apple’s “Creating the Remote Notification Payload”.

For the GcmPayload format, see Google’s documentation of GCM downstream HTTP messages (JSON).

For the FcmPayload format, see Google’s documentation of FCM downstream HTTP messages (JSON).

The total size of the payload is 4KB on APNs, FCM and GCM.

This resource accepts the following methods:

  • POST /v1/apps/:pusher_app_id/notifications. Push a new notification for the app :pusher_app_id. The request body must be in the above format. A successful response will be a 200.

    When a notification is posted, we will queue the notification for delivery to all clients which were subscribed to the interest in the list at the time that the notification was posted.

Using webhooks

Each POST request you make to the notifications endpoint can include a webhook_url and a webhook_level. These are used to specify an external URL to which Pusher will send information about the sent push notifications. This is particularly useful for debugging failed push notifications.

The webhook_level is a debug level, which can be set to either "INFO" or "DEBUG". If set to "INFO", Pusher only makes requests to the endpoint when errors occur. If set to "DEBUG", Pusher makes requests to your specified URL for every notification.

All requests use the POST method. The body is a JSON array of log messages. Each log message is a JSON object. Successful notifications, if "webhook_level" is set to "DEBUG", generate a log message like this:

{
  "success": true,
  "platform": "gcm",
  "...": "..."
}

Have you tried using the search to find what you’re after? If you still have a question then get in touch with us and let us help you out.