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
}

The "body" field is a serialized JSON object to emphasize the fact that the value in the associated "HMAC" field signs the entire contents of the "body" field.

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": "You've got mail!",
  "body": "There are current 2 messages in your inbox.",
  "url": "http://mail.google.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.

Message HMAC

The "HMAC" field is included to verify that the message has not been tampered with by a third party. It is calculated by signing the contents of the "body" field using the standard HMAC algorithm with the SHA-256 hash function.