Storyline notifications

You can register a callback url to receive notifications about users storyline updates. The url can be defined in the development tab in apps management.
The url must be a valid http or https url accepting and responding to HTTP POST requests.
The notification should arrive within short time of any update affecting storyline, however multiple updates within a short period may be batched to single notification.
The storylines get updated usually every couple of hours and when user opens the app in phone.
Notifications are sent for users which have an active authorization, meaning that there is at least one non-revoked access token for the user. Note that this means the notification is also sent if an access token is expired but can still be refreshed.
We make best effort attempt to deliver the notifications, but cannot guarantee their perfect reliability.

Expected response

The request is expected to return in 3 seconds, after which it is regarded as a timed out response.
Response status codes other than 200 are considered as an error response.
Any redirections are not followed. The response body and headers are ignored.
Any notifications that failed to be delivered are simply discarded.

Throttling

If the callback url repeatedly times out or returns an error, the notifications may be suppressed or throttled for a while.

Request signing

All notification requests are signed with Base64 encoded HMAC-SHA1 signature. The signature is calculated as HMAC_SHA1(<your client secret>,<request body>|<timestamp>|<nonce>), in other words the client secret as the key and request body, timestamp and nonce concatenated as the message data. HTTP headers are not included in the signature.
The headers X-Moves-Signature, X-Moves-Timestamp and X-Moves-Nonce contain the signature, timestamp and nonce values. The timestamp is a unix timestamp, seconds since Jan 01 1970 00:00:00 GMT.
Example:

X-Moves-Signature: xMbCdVO044lZCHiwEDBty+ae1oA=
X-Moves-Timestamp: 1390571569
X-Moves-Nonce: abcdefghijklmnopqrstuvwxyz

Request

Content-Type: application/json; charset=utf-8
User-Agent: Moves API
{
  "userId": 123456789,
  "storylineUpdates": [
      {
        "reason": "DataUpload",
        "startTime": "20121212T072747Z",
        "endTime": "20121212T093247Z",
        "lastSegmentType": "place",
        "lastSegmentStartTime": "20121212T082747Z"
      },
      {
        "reason": "ActivityUpdate",
        "startTime": "20121212T072747Z",
        "endTime": "20121212T073247Z"
      },
      {
        "reason": "PlaceUpdate",
        "startTime": "20121212T082747Z",
        "endTime": "20121212T093247Z"
      },
      {
        "reason": "PlaceRename",
        "placeId": 123456
      }
  ]
}
  • userId: the user ID
  • storylineUpdates: JSON array with storyline update events

    Storyline update event
  • reason: reason for this update event. Note that there maybe additional reasons in the future
    • DataUpload: storyline was updated due to new data collected and processed
    • ActivityUpdate: user added, corrected or deleted activities
    • PlaceUpdate: user corrected or deleted a place
    • PlaceRename: user renamed a place. Note that the startTime and endTime are NOT included in the update.
  • startTime (optional): earliest time affected by this update event in ISO 8601 (yyyyMMdd’T’HHmmssZ) format, always in UTC
  • endTime (optional): latest time affected by this update event in ISO 8601 (yyyyMMdd’T’HHmmssZ) format, always in UTC
  • placeId (optional): id of the place that was renamed (with PlaceRename)
  • lastSegmentType (optional): type of the last segment, one of place, move or off (with DataUpload). “off” segment type indicates that Moves tracking had been disabled for some reason.
  • lastSegmentStartTime (optional): startTime of the last segment in ISO 8601 (yyyyMMdd’T’HHmmssZ) format, always in UTC (with DataUpload)