CloudServices/Notifications/Specification/POSTOffice

The POST Office supports a very simple REST API, allowing web apps to send notifications to a subscription token.

Sending Notifications

1. Web app sends notification to POST Office.

   W: POST /1.0/notification HTTP/1.1
   W:
   W: {
        "body": "{\"token\":\"BASE64==\", ...}",
        "HMAC": "BASE64=="
      }
   P: HTTP/1.1 202 ACCEPTED
   

Message Body

The "body" field of the message is a JSON serialization of the message metadata and the encrypted payload. Metadata includes the subscription token, when the message was sent, and when the message expires. The metadata should be thought of as information that aids in routing the message to its intended recipient, as well as providing any other information about the message that may be of use while it is en-route. Any other information should be placed in the encrypted payload to ensure privacy.

A typical message body would look like the following:

{ 
  "token": "BASE64==", // Subscription Token
  "timestamp": ########, // UTC Timestamp in seconds (OPTIONAL)
  "ttl": ######## (in seconds), // Time To Live in seconds (OPTIONAL)
  "ciphertext": "BASE64==", // Encrypted payload
  "IV": "BASE64==", // Initialization vector to use in decrypting ciphertext
}

Ciphertext Contents

The "ciphertext" field is a string encrypted with the encryption key using AES-256-CBC and base-64 encoded. The contents of the payload differ based on the type of message, however it is typically a serialized JSON object. For example, the payload of a standard notification will look like the following:

{
  "type":"notification",
  "title":"...",
  "body":"...",
  "url":"http://foobar.com"
}

The reason no specific format is required for the payload is that it should be up to clients to decide what kind of formats they wish to support. The higher-level goal is to build a secure "message-routing" solution. A push notification service is simply a special subset of a message routing solution.