Files notification

The files notification API informs 3rd party application of new available files exported from X3 configuration previously paired thanks to the notification Url entered while registering the app.

• Requirements for this step:

  • Notification Url of 3rd party application to call: in our example, it will be https://myapp.3rdparty.com/notification

    

  • A valid access token “XXXXXXX” for this endpoint obtained as shown in the previous step Token management

• API call examples:

  In a scenario of an application consuming files exported by X3 configuration, the obvious need of this application is to be notified when a new file is available for downloading. When such event happens, the API gateway calls the notification URL with the following payload:

        {
            "notificationId" : "<uuid of the notification>",
            "source" : "dataDeliveryApi",
            "customerUrl" : "<url of customer>",
            "customerID" : "<Id of the customer>",
            "datetime" : "<UTC datetime when the notification was created>",
            "detailUrl" : "https://api.sagex3.com/v1/notification/<uuidOfNotification>"
        }
  

  with an authentication header name “HMAC_SHA256” and the value is the sha256 of the payload with its clientID obtained while registering with Sage App Registry. Once the application receives the request and regenerates its own unique HMAC, it compares the two HMACs. If they are equal, the request content is authentic and the application can use “detailUrl” inside the payload in the next step. This process is often called a secret handshake which ensures that a malicious source cannot alter the payload.

  As designed, the content of the notification is not sent directly to the application, instead it needs to use the notification consume API to get the detail of the notification :

  • By curl command:

        curl -H "Authorization: Bearer XXXXXXX" https://api.sagex3.com/v1/notification/<uuidOfNotification>
    

        {
            "notificationID" : "<uuid of the notification>",
            "applicationId" : "<id of the 3rd party application>",
            "customerCode" : "<customer code>",
            "customerId" : "<id of the customer>",
            "customerUrl" : "<url of customer>",
            "datetime" : "2020-04-10T16:59:57.518Z",
            "source" : "dataDeliveryApi",
            "payload" : '{"eventKind":"dataDeliveryFileAvailable","folder":"SEED","fileName":"result.txt","downloadUrl":"https://api.qa-sagex3.com/v1/datadelivery/SEED?filename=result.txt"}'
        }