Child pages
  • HTTP Push Notification User Guide
Skip to end of metadata
Go to start of metadata

Document History

Version

Date

Reason

1.0

01.06.2014

Initial version

1.102.09.2014Updated demonstration code




 

M800 Push Notification API

maaii Notification Service provides availability and reliability to send client side real-time push / in-app messages. API server support following features and messages by given API.

Send push notification

Endpoint

Request URL/api/1.0/push/username@carrier
MethodPOST
Acceptsapplication/json
Producesapplication/json

Parameters

NameTypeOptionalDescription
usernamestringnoreceiver's username
carrierstringnoreceiver's domain name

Request

Request Specification

Field NameField TypeOptionalField Description

appMessage.content

StringnoSome notification text, will be sent using IM channel
push.contentStringyesSome notification text, will be sent using push channel, if available.
senderStringyesoptionally to set the sender of the message. Allow only with format of username@carrierName which is JID alike.

Successful Response Example

{

   "requestId" : "some request id defined in the request."

}

 

Encryption

All interactions between the developers are encrypted using HTTPS. While maaii API server only accepts encrypted traffic, and it is the responsibility of the developer to set up an HTTPS service on his side to secure the callback reception.

Authentication

All requests sent by the developer must be signed. The purpose of the signature is to ensure the identity of the developer and the authenticity of the requests. Similarly, callback requests sent to the developer server by the maaii API server are also signed to allow the developer to verify their authenticity.

Signature process

In order to authenticate and assert the validity of a request, all requests made by a developer have to be authenticated. The authentication uses a custom HTTP authorization scheme, based on request signing:

Where {developerKey} is the developer key, {nonce} is number used to make the request unique and prevent replay attacks and {signature} is the request's signature. This is computed based on the actual request payload and is signed using the developer secret with the following signing mechanism:

If the request does not contain a payload (no Content-Type / Content-Md5), its value should be an empty string. This means the line feed is still required in the signature computation.

The Date element of the signature is taken from the "X-M-Date".

The date mentioned in the request will be used to verify the request is not replayed, the server determines an acceptable time range for a request to be processed, if the date is not within this range, it will be rejected.

Example

We try to post to the following example URI:

Endpoint called

With this JSON payload

Example payload, Content-Md5 = 2aa2f9b90fea8843a78e434dff26f6b6

Assuming the developer key is "a-demo-key" and the developer secret is "a-demo-secret", the signature would be:

The HTTP request should then contain the Authorization with the computed signature as follows:

Complete POST request

The presence / absence of "Content-Md5", "Content-Type" and "Content-Length" do not affect the authorization process, it relies solely on the actual request, payload and the authorization header.

 

 

Testing Tools

All examples given in the previous section can be verified and reproduced manually with the help of online tools.

When using an online tool, be careful to not include extra white space or line returns as this will affect the final outcome.

Content-MD5

The following online tools can be used to generate MD5:

http://www.miraclesalad.com/webtools/md5.php

http://www.md5hashgenerator.com/index.php

Example 

SHA-256 HMAC

The following online tool can be used to generate SHA-256 HMAC signatures:

http://jetcityorange.com/hmac/

Example 

 

M800 Confidential. All rights reserved. 2014 © 

  • No labels