Pulse v2.0 API
Pulse, the evolution of Intellischool's "Pulse alerts" feature, generates events when certain data thresholds are met. The Pulse API enables authorised partners to integrate Pulse notifications, alerts, and reports into their applications.
To use this API, you must be an authorised partner.
Base URI
The Pulse API can be accessed via any of the regional Intellischool API services, or via the global unified API service. The route prefix is always /v2/alerts.
For example, to access the Pulse API via the global unified endpoint:https://api.intellischool.net/v2/alerts/{endpoint}
Alternatively, to access the Pulse API via the AU-NSW regional service: https://api.nsw.intellischool.com.au/v2/alerts/{endpoint}
Or the SG regional service:https://api.intellischool.sg/v2/alerts/{endpoint}
Required scopes
In order to query the Pulse API, your auth token must have at least one of the following scopes enabled. As this is a restricted API, these scopes can only be enabled by contacting Intellischool.
-
- Name
https://schema.intellischool.net/scope/alerts/messages.read- Type
- Description
Read-only access to getMessage endpoint.
-
- Name
https://schema.intellischool.net/scope/alerts/webhooks.write- Type
- Description
Enables your app to manage webhooks programmatically with the getWebhook, newWebhook, updateWebhook and deleteWebhook endpoints.
getMessage
Gets the contents of a Pulse message.
Required attributes
- Name
-
id - Type
- uuid
The UUID of the message to be retrieved.
Request
Response
deleteWebhook
Deletes one of your app's webhooks, as specified by the ID parameter.
Required attributes
- Name
-
id - Type
- uuid
The ID of the webhook you would like to delete.
Request
Response
newWebhook
Register a new webhook for your app. Parameters should be provided in JSON format, with a content type of application/json in the headers of the request.
Required attributes
- Name
-
endpoint - Type
- string
The URL to which Intellischool should
POSTwebhooks.
- Name
-
type - Type
- enum ("notification-only" | "full-payload")
Whether Intellischool should send only the notification content, or the full payload of a Pulse message to the webhook consumer.
Request
Response
getWebhook
Get all your app's registered webhooks, or a specific webhook if an ID is provided.
Optional attributes
- Name
-
id - Type
- uuid
The UUID of a specific webhook to retrieve
Request
Response
updateWebhook
Update one of your app's webhooks. Note that you must supply at least one of the optional attributes for this endpoint.
Update fields should be supplied in JSON format, with a content type header of application/json.
The endpoint will only return fields that have been updated in the updated_props object.
Required attributes
- Name
-
id - Type
- uuid
The ID of the webhook to be updated.
Optional attributes
- Name
-
endpoint - Type
- string
The new endpoint URL that Intellischool should
POSTto.
- Name
-
type - Type
- enum ("notification-only" | "full-payload")
The type of webhook that should be emitted.
Request
Response
Webhooks
Authorised partners can opt to subscribe to webhooks that alert their app when a new alert message is generated. The primary use case for Pulse webhooks is creating a notification inside your app with the content (or a link to the content) of the new alert.
Trigger events
Webhooks are triggered for every message to every user. For example, if the same alert is sent to multiple users, the webhook will be triggered for each user. When designing your integration, you should consider the potential load on your webhook consumption endpoint. Most schools will have Pulse configured to send messages once per day, so your consumption endpoint will experience a spike in demand at that time.
When a webhook is triggered, Intellischool will POST the signed webhook payload to the registered webhook URI.
Registering a webhook
Use the getWebhook, newWebhook, updateWebhook and deleteWebhook endpoints to manage the webhooks for your app programmatically.
Types of webhook
There are two types of Pulse webhooks available: a notification-only webhook and the full-payload webhook. Your app does not need to subscribe to both, as they are both triggered upon the generation of a new alert message.
You should subscribe to the notification-only webhook if your app does not need the full message payload when generating a notification. Your notification may then link to a page within your app that loads the message content from this API's getMessage endpoint, or you can link directly to the message within Intellischool's native app.
You should subscribe to the full-payload webhook if your integration requires the full message payload immediately. Note that this payload can sometimes exceed 1MB per message for schools/individuals that use the Pulse system heavily.
Authenticating webhooks
Webhook payloads are posted to your registered endpoint as a signed JWT. You should always validate that a webhook is from Intellischool.
To do so, you can authenticate the JWT signature against Intellischool's global JWKS. The kid in the JWT header must match a public key in the JWKS.
Webhook response requirements
When Intellischool invokes a POST request to your webhook consumer, the consumer must respond within 30 seconds with a successful HTTP code (between 200 and 299).
If your consumer responds with any code other than a success code, or if it fails to respond at all, Intellischool will automatically retry the request up to 10 times. The first retry will occur after 5 seconds, after which the retry interval will double for each failed request (to a maximum of ~43 minutes). If, after 10 retries, your webhook consumer does not send a successful response, the alert message will be marked as undeliverable.