edit-icon download-icon

Notification(HttpEndpoint) APIs

Last Updated: Jun 07, 2017

Http Endpoint

Description

The Message Service pushes notifications to endpoints by sending POST requests. Notifications are in two formats: XML (complete format) and SIMPLIFIED (simplified format).

For a notification in XML format, the request body contains the body and meta information of the push message.

For a notification in SIMPLIFIED format, the request body contains only the original message body, and MessageId is carried in the request header.

Note : There is a sample code file named HttpEndpoint.java in folder “src/main/java/com/aliyun/mns/sample” of Java SDK to show how to implement a http endpoint for receiving push messages from Message Service. What’s more, Message Service provides a debug tool to help test the HttpEndpoint locally: HttpEndpoint Debug Tool.

Request

A request mainly includes the following parts:

  • Request line

    POST /notifications HTTP/1.1.

    /notifications is used by default. If the endpoint specified by the subscriber contains a URI, /notifications is replaced with the URI.

  • Special URI parameter

    None

  • Special request header

Parameter name Description Remarks
Authorization Signature of the push request Available in XML and SIMPLIFIED formats
x-mns-signing-cert-url Address of the signature certificate (Base64 encoded) Available in XML and SIMPLIFIED formats
x-mns-request-id Request ID of the push message Available in XML and SIMPLIFIED formats
x-mns-message-id ID of the push message Available only in SIMPLIFIED format
x-mns-message-tag Tag of the push message Available only in SIMPLIFIED format
  • Request Body

    For a notification in XML format, the request body is in XML format and contains the body and meta information of the message.

Parameter name Description
TopicOwner Owner of the subscribed topic
TopicName Name of the subscribed topic
Subscriber Name of the subscriber
SubscriptionName Name of the subscription
MessageId ID of the message
Message Body of the message
MessageMD5 MD5 value of the message
MessageTag Message tag (used for message filter)
PublishTime Time when a message is published, defined as the number of milliseconds that have elapsed since 00:00:00 000, January 1, 1970
SigningCertURL Address of a signature certificate, available only in XML format. (NOTE: This parameter is not recommended and is only used for compatibility with beta users. It will not be supported starting from July 2016.)

For a notification in SIMPLIFIED format, the request body contains only the published message body.

Response

The response message includes three parts: return status line, HTTP header, and message body.

  • HTTP Status Code

    HTTP/1.1 204 No Content

    Status Code 204 is returned when the notification is processed normally.

    Status Code 403 is returned when signature authentication is not passed.

    Status Code 500 is returned when any other error occurs.

  • Special response header

    None

  • Response Body

    None

Request example:

XML format

  1. POST /notifications HTTP/1.1
  2. Host: company.com
  3. Date: Tue, 08 Dec 2015 06:42:00 GMT
  4. Content-Length: 300
  5. Content-Type: text/xml;charset=utf-8
  6. Content-MD5: OGQzNjAwYjIwMWFiMTliZDlhNzc4YjAwZjc5MGQ4NDE=
  7. Authorization: QSNS+vn3IqJI4lOh4X/dxTv7Qebi/wrEaBJlzFFTc0hJVRUmrHLQo24ojBUETpz48+jrsjxMGPJTILDw752Jww==
  8. User-Agent: Aliyun Notification Service Agent
  9. x-mns-request-id: 56667BB81FD0E7D1200024A0
  10. x-mns-version: 2015-06-06
  11. x-mns-signing-cert-url: aHR0cDovL21uc3Rlc3Qub3NzLWNuLWhhbmd6aG91LmFsaXl1bmNzLmNvbS94NTA5X3B1YmxpY19jZXJ0aWZpY2F0ZS5wZW0=
  12. <?xml version="1.0" encoding="utf-8"?>
  13. <Notification xlmns="http://mns.aliyuncs.com/doc/v1/">
  14. <TopicOwner>$TopicOwner</TopicOwner>
  15. <TopicName>$TopicName</TopicName>
  16. <Subscriber>$Subscriber</Subscriber>
  17. <SubscriptionName>$SubscriptionName</SubscriptionName>
  18. <MessageId>6CC4D900CA59A2CD-1-15180534A8F-200000002</MessageId>
  19. <Message>{1:"a", 2:"b"}</Message>
  20. <MessageMD5>F1E92841751D795AB325861034B5CB55</MessageMD5>
  21. <MessageTag>important</MessageTag>
  22. <PublishTime>1449556920975</MessagePublishTime>
  23. </Notification>

SIMPLIFIED format

  1. POST /notifications HTTP/1.1
  2. Host: company.com
  3. Date: Tue, 15 Dec 2015 09:12:46 GMT
  4. Content-Length: 487
  5. Content-Type: text/plain;charset=utf-8
  6. Content-MD5: NmY4Njk0MzlmNzg3NTFkMTJiN2M5OWE4ZmYzNTU4ZWQ=
  7. Authorization: aXZIpRkRmIavmwceCyrPatB7SaEbOJdWpmFWYX3nFwtmaixK/M/3kl1njY0pgM7mrIB7NlBv5NfUZNkcIjlO4A==
  8. User-Agent: Aliyun Notification Service Agent
  9. x-mns-message-id: 6CC4D900CA59A2CD-1-15180534A8F-200000002
  10. x-mns-message-tag: important
  11. x-mns-request-id: 566FD963B2B71C44481F701A
  12. x-mns-signing-cert-url: aHR0cDovL21uc3Rlc3Qub3NzLWNuLWhhbmd6aG91LmFsaXl1bmNzLmNvbS94NTA5X3B1YmxpY19jZXJ0aWZpY2F0ZS5wZW0=
  13. x-mns-version: 2015-06-06
  14. {1:"a", 2:"b"}

Response example:

  1. HTTP/1.1 204 No Content
Thank you! We've received your feedback.