HTTP Endpoints for Notifications

Autopush exposes three HTTP endpoints:

/wpush/...

This is tied to the Endpoint Handler ~autopush.web.webpush.WebPushHandler This endpoint is returned by the Push registration process and is used by the AppServer to send Push alerts to the Application. See send.

/m/...

This is tied to ~autopush.web.message.MessageHandler. This endpoint allows a message that has not yet been delivered to be deleted. See cancel.

/v1/.../.../registration/...

This is tied to the reg_calls Handlers. This endpoint is used by devices that wish to use bridging protocols to register new channels.

NOTE: This is not intended to be used by app developers. Please see the Web Push API on MDN for how to use WebPush. See bridge_api.

Push Service HTTP API

The following section describes how remote servers can send Push Notifications to apps running on remote User Agents.

Lexicon

{UAID} The Push User Agent Registration ID

Push assigns each remote recipient a unique identifier. {UAID}s are UUIDs in lower case, undashed format. (e.g. '01234567abcdabcdabcd01234567abcd') This value is assigned during Registration

{CHID}
The Channel Subscription ID

Push assigns a unique identifier for each subscription for a given {UAID}. Like {UAID}s, {CHID}s are UUIDs, but in lower case, dashed format( e.g. '01234567-abcd-abcd-abcd-0123456789ab'). The User Agent usually creates this value and passes it as part of the Channel Subscription. If no value is supplied, the server will create and return one.

{message-id}
The unique Message ID

Push assigns each message for a given Channel Subscription a unique identifier. This value is assigned during Send Notification.

Response

The responses will be JSON formatted objects. In addition, API calls will return valid HTTP error codes (see errors sub-section for descriptions of specific errors).

For non-success responses, an extended error code object will be returned with the following format:

{
    "code": 404,  // matches the HTTP status code
    "errno": 103, // stable application-level error number
    "error": "Not Found", // string representation of the status
    "message": "No message found" // optional additional error information
}

See Errors for a list of the errors, causes, and potential resolutions.

Calls

Send Notification

Send a notification to the given endpoint identified by its push_endpoint. Please note, the Push endpoint URL (which is what is used to send notifications) should be considered "opaque". We reserve the right to change any portion of the Push URL in future provisioned URLs.

The Topic HTTP header allows new messages to replace previously sent, unreceived subscription updates. See topic.

Call:

https://updates.push.services.mozilla.com/wpush/v1/...

If the client is using webpush style data delivery, then the body in its entirety will be regarded as the data payload for the message per the WebPush spec.

Note Mozilla reserves the right to change the endpoint at any time. Please do not "optimize" by only storing the last token element of the URI. There will be tears.

Note Some bridged connections require data transcription and may limit the length of data that can be sent. For instance, using a GCM/FCM bridge will require that the data be converted to base64. This means that data may be limited to only 2744 bytes instead of the normal 4096 bytes.

Reply:

{"message-id": {message-id}}

Return Codes:

Note The Push RFC notes the HTTP response codes that should be returned. Autopush cannot support the Push Message Receipt at this time, so Autopush should only return a 201 response. (Previously, Autopush would return a 202 indicating that the message was stored for later retrieval.) Autopush cannot guarantee end-to-end delivery of a message due to the nature of how it handles subscription updates to mobile devices. The "Bridge" protocols do not support this feature, and if possible, Autopush should not disclose the type of UserAgent to the Subscription provider.

statuscode 404
Push subscription is invalid.
statuscode 410 Push subscription is no longer available.
statuscode 201
Message delivered to node or bridge the client is connected to.

Message Topics

Message topics allow newer message content to replace previously sent, unread messages. This prevents the UA from displaying multiple messages upon reconnect. A blog post provides an example of how to use Topics, but a summary is provided here.

To specify a Topic, include a Topic HTTP header along with your send. The topic can be any 32 byte alpha-numeric string (including "_" and "-").

Example topics might be MailMessages, Current_Score, or 20170814-1400_Meeting_Reminder

For example:

curl -X POST \
    https://push.services.mozilla.com/wpush/abc123... \
    -H "TTL: 86400" \
    -H "Topic: new_mail" \
    -H "Authorization: Vapid AbCd..." \
    ...

Would create or replace a message that is valid for the next 24 hours that has the topic of new_mail. The body of this might contain the number of unread messages. If a new message arrives, the Application Server could send a second message with a body containing a revised message count.

Later, when the User reconnects, she will only see a single notification containing the latest notification, with the most recent new mail message count.

Cancel Notification

Delete the message given the message_id.

Call:

https://updates.push.services.mozilla.com/wpush/v1/...

Parameters:

None

Reply:

{}

Return Codes:

See errors.

Push Service Bridge HTTP Interface

Push allows for remote devices to perform some functions using an HTTP interface. This is mostly used by devices that are bridging via an external protocol like GCM/FCM or APNs. All message bodies must be UTF-8 encoded.

API methods requiring Authorization must provide the Authorization header containing the registration secret. The registration secret is returned as "secret" in the registration response.

Lexicon

For the following call definitions:

{type}
The bridge type.

Allowed bridges are gcm (Google Cloud Messaging), fcm (Firebase Cloud Messaging), and apns (Apple Push Notification system)

{app_id}
The bridge specific application identifier

Each bridge may require a unique token that addresses the remote application For GCM/FCM, this is the SenderID (or 'project number') and is pre-negotiated outside of the push service. You can find this number using the Google developer console. For APNS, this value is the "platform" or "channel" of development (e.g. "firefox", "beta", "gecko", etc.) For our examples, we will use a client token of "33clienttoken33".

{instance_id}
The bridge specific private identifier token

Each bridge requires a unique token that addresses the application on a given user's device. This is the "Registration Token" for GCM/FCM or "Device Token" for APNS. This is usually the product of the application registering the {instance_id} with the native bridge via the user agent. For our examples, we will use an instance ID of "11-instance-id-11".

{secret}
The registration secret from the Registration call.

Most calls to the HTTP interface require a Authorization header. The Authorization header is a simple bearer token, which has been provided by the Registration call and is preceded by the scheme name "Bearer". For our examples, we will use a registration secret of "00secret00".

An example of the Authorization header would be:

    Authorization: Bearer 00secret00

{vapidKey}
The VAPID Key provided by the subscribing third party

The VAPID key is optional and provides a way for an application server to voluntarily identify itself.

Please Note: While the VAPID key is optional, if it is included, the VAPID asserion block must contain a sub field containing the publishing contact information as a vaild URI designator. (e.g. mailto:admin+webpush@example.org or https://example.org/contact). As an example, a minimal VAPID assertion block would contain:

{"aud": "https://updates.push.services.mozilla.com", "exp": 1725468595, "sub": "mailto:admin+webpush@example.com"}

Where exp and sub reflect the expiration time and publishing contact information. The contact information is used in case of an issue with use of the Push service and is never used for marketing purposes.

When the VAPID key is provided, autopush will return an endpoint that can only be used by the application server that provided the key.

The VAPID key is formatted as a URL-safe Base64 encoded string with no padding.

Calls

Registration

Request a new UAID registration, Channel ID, and set a bridge type and 3rd party bridge instance ID token for this connection. (See ~autopush.web.registration.NewRegistrationHandler)

NOTE: This call is designed for devices to register endpoints to be used by bridge protocols. Please see Web Push API for how to use Web Push in your application.

Call:

POST /v1/{type}/{appid}/registration

This call requires no Authorization header.

Parameters:

{"token":{instance_id}, "key": {vapidkey}}

Note

The VAPID key is optional

If additional information is required for the bridge, it may be included in the parameters as JSON elements. Currently, no additional information is required.

Reply:

`{"uaid": {UAID}, "secret": {secret},
"endpoint": "https://updates-push...", "channelID": {CHID}}`

example:

 POST /v1/fcm/33clienttoken33/registration

 {"token": "11-instance-id-11", "key": "AbC12ef0"}

 {"uaid": "01234567-0000-1111-2222-0123456789ab",
 "secret": "00secret00",
 "endpoint": "https://updates-push.services.mozaws.net/push/...",
 "channelID": "00000000-0000-1111-2222-0123456789ab"}

Return Codes:

See errors.

Token updates

Update the current bridge token value. Note, this is a *PUT* call, since we are updating existing information. (See ~autopush.web.registration.UaidRegistrationHandler)

Call:

  PUT /v1/{type}/{appid}/registration/{uaid}
  Authorization: Bearer {secret}

Parameters:

{"token": {instance_id}}

Note

If additional information is required for the bridge, it may be included in the parameters as JSON elements. Currently, no additional information is required.

Reply:

{}

example:

 PUT /v1/fcm/33clienttoken33/registration/abcdef012345
 Authorization: Bearer 00secret00

 {"token": "22-instance-id-22"}

{}

Return Codes:

See errors.

Channel Subscription

Acquire a new ChannelID for a given UAID. (See ~autopush.web.registration.SubRegistrationHandler)

Call:

  POST /v1/{type}/{app_id}/registration/{uaid}/subscription
  Authorization: Bearer {secret}

Parameters:

{key: {vapidKey}}

Note VAPID key is optional

Reply:

{"channelID": {CHID}, "endpoint": "https://updates-push..."}

example:

 POST /v1/fcm/33clienttoken33/registration/abcdef012345/subscription
 Authorization: Bearer 00secret00

 {"key": "AbCd01hk"}

 {"channelID": "01234567-0000-1111-2222-0123456789ab",
  "endpoint": "https://updates-push.services.mozaws.net/push/..."}

Return Codes:

See errors.

Unregister UAID (and all associated ChannelID subscriptions)

Indicate that the UAID, and by extension all associated subscriptions, is no longer valid. (See ~autopush.web.registration.UaidRegistrationHandler)

Call:

  DELETE /v1/{type}/{app_id}/registration/{uaid}
  Authorization: Bearer {secret}

Parameters:

{}

Reply:

{}

Return Codes:

See errors.

Unsubscribe Channel

Remove a given ChannelID subscription from a UAID. (See: ~autopush.web.registration.ChannelRegistrationHandler)

Call:

  DELETE /v1/{type}/{app_id}/registration/{uaid}/subscription/{CHID}
  Authorization: Bearer {secret}

Parameters:

{}

Reply:

{}

Return Codes:

See errors.

Get Known Channels for a UAID

Fetch the known ChannelIDs for a given bridged endpoint. This is useful to check link status. If no channelIDs are present for a given UAID, an empty set of channelIDs will be returned. (See: ~autopush.web.registration.UaidRegistrationHandler)

Call:

  GET /v1/{type}/{app_id}/registration/{UAID}/
  Authorization: Bearer {secret}

Parameters:

{}

Reply:

{"uaid": {UAID}, "channelIDs": [{ChannelID}, ...]}

example:

GET /v1/gcm/33clienttoken33/registration/abcdef012345/
Authorization: Bearer 00secret00
{}

 {"uaid": "abcdef012345",
 "channelIDS": ["01234567-0000-1111-2222-0123456789ab", "76543210-0000-1111-2222-0123456789ab"]}

Return Codes:

See errors.

Mozilla Autopush Server