Skip to main content

Webhooks

OpenAPI definition

When certain events happen in the Xporter platform, we can automatically notify you with an event posted to a webhook URL you specify. There are four different categories of event that we can notify to your webhook URL - Authentication events, Data Availability events, Data Writeback events and Database events.

Authentication Events​

When a you invite a school to share data and that school completes the authorisation process, we will call your specified webhook with a payload containing the school secret and a parameter indicating if the school has Xporter on Demand installed. We will also notify you when a school has completed the installation step of onboarding, connected succesfully to their MIS and after jobs to collect school data have run for the first time. This callback will have the install completed parameter set to true. If a school already has Xporter on Demand installed we will send the same payload but without the delay of running the jobs first.

  • Example Callback
schoolSecret=0755658d-0c81-4bfc-93a2-77b9e873914f&schoolId=3286198&schoolEmail=rrainey%40groupcall.com
&schoolName=Testing+School&templateScopes=AssessmentResults%2CAttendance%2CSchool%2CSEN%2CSENTypes%2CStudent%2CStudentDemographic%2CStudentExtended%2CStudentReligion%2CWritebackAttendance
&scopes=AssessmentResults%2CAttendance%2CSchool%2CSEN%2CSENTypes%2CStudent%2CStudentDemographic%2CStudentExtended%2CStudentReligion%2CWritebackAttendance
&thirdParty=XporterOnDemand&partnerId=live.example.app

Data Availability Events​

Every endpoint now supports an additional GET parameter "callbackUrl". If you pass this paramaeter with a URL you can receive a POST message. We will perform the DBStatus checking for you and call you back with the DBStatus object once all component databases are status "OK".

  • Example
/attendancefordate?date=2017-09-23&callbackUrl=https://xporter.groupcall.com/TryIt/callback?estab=3281102&id=attendance1

We suggest you provide the Estab and your own abritrary ID so you know which request the callback is referring to, if you are making multiple requests against different schools.

The maximum wait period before determining there is a problem with a callback is 10 minutes. After this time, we will call you back with an appropriate status. If there is an error received immediately, then we will call you back as soon as we have that error as well. In this scenario, based on the databases statuses received in the object, the recommended action would be to request the data direct, so we can return you data from the cache.

Data Writeback Events​

When you use one of the POST endpoint to write data back to the MIS, Xporter on Demand will call you back when it has finished to let you know the outcome of the request so you don't have to wait for it!

All you need to do is implement a callback URL and supply it in the JSON object when calling the endpoint. Examples of this can be seen in the Sandbox when viewing the POST endpoints. Here is an example of a session attendance writeback object, with a callback URLimplemented:

{
    "Marks": [
        {
            "StudentId": "9919",
            "MarkType": "S",
            "Date": "2016-08-24",
            "Session": "AM",
            "Mark": "\\"
        }
    ],
    "callback": [
        {
            "Method": "POST",
            "Url": "https://xporter.groupcall.com/TryIt/Callback/?id=Attendance&estab=3288882"
        }
    ]
}
tip

You can view the responses from the example callback URL via our Callback Test Site

Each of the POST endpoints will have their own specific documentation on the Sandbox where you can find more information and detail about the information returned to you.

Database Webhooks​

Registering for Notifications from the Xporter API Platform​

It is possible to register an Xporter application to receive notifications from the Xporter API platform when data changes, instead of polling for data updates every night.

The advantage of this approach is that applications can request data only after it has been updated, rather than potentially fetching and syncing data before the school's daily update has completed.

If no data changes occur, no webhooks are triggered, allowing applications to avoid making unnecessary API calls.

Registering for Webhook Events​

To register for webhook events, make a call to the API using the STS token for your establishment.

Example:

await client.SendWebHookAsync(
  "https://xportertesting.groupcall.com/tryit/callback?estab=3281234&database=xodschooldata",
  "XodSchoolData",
  "GET"
);

Alternatively, you can use a POST request:​

POST https://xporter.groupcall.com/api/v1/Webhook
{
  "url": "https://xporter.groupcall.com/TryIt/Callback?estab=3281234&database=xodschooldata",
  "DatabaseName": "XodSchoolData"
}

Parameters​

  • url: The callback URL for your application.
  • DatabaseName: The name of the database you are registering for updates.
tip

You can set the GET parameters you wish to process when the callback is triggered, such as the school's establishment number and the database name.

Each webhook configuration is unique for a combination of Application (RP) + Establishment (school) + Database. Registering a new webhook for the same combination will overwrite any existing one.

Receiving Webhook Events​

When a database change event is generated, a call will be made to the registered URL for the Application / Establishment / Database. This call will contain the URL parameters as originally registered. Your callback controller should process these parameters and then initiate the data request within your application.