Event notification service

The Drillster event notification service provides a collection of webhooks. It offers a way for external systems to subscribe to certain events that originate in the Drillster system. As and when these events occur, subscribers are notified via an HTTP call.

Supported event notifications

The push API consists of the following notification types:

Notification type Description
ACCOUNT_CREATED Fires when a new user account is created.
GROUP_MEMBER_ADDED Fires as and when a member has been added to a group.
GROUP_MEMBER_REMOVED Fires as and when a member has been removed from a group.
OBJECTIVE_BECAME_NOK Fires when a group members is no longer compliant with an objective.
OBJECTIVE_BECAME_OK Fires when a group member becomes compliant with an objective.
QUESTION_ANSWERED Fires as and when a drill question is answered by a group member.
TEST_COMPLETED Fires as and when a test is completed.

Deprecated event types

There are some deprecated event types that are no longer available for new integrations.

Data format and transport

Push notifications are sent as HTTP POST or PUT requests, depending on the preference of the recipient. They contain a JSON object in the request body as payload.

The target URL is composed of a base URL, configured for the recipient, with the event name appended.

Example

POST https://www.example.com/drillster/GROUP_MEMBER_ADDED

Push messages can only be sent via https on port 443, with a valid, publicly signed, SSL certificate. Self-signed certificates are not supported. Plaintext messages (port 80) are not supported. Finally, an authentication mechanism based on basic authentication is available.

In order to guarantee a robust integration, any messages that are not properly acknowledged will be retried. Please see the documentation regarding the retry mechanism for details.

Subscribing to events

In order to make use of push notifications, you must have an event receiver set up. Please refer to the documentation for instructions.

If you require assistance in using push notifications, please contact us at support@drillster.com.

Changes and compatibility

The event types and object models will continue to be offered until an upgrade path has been communicated with all affected users. However, because of the extensible nature of the JSON file format, it is possible that additional attributes will be added to the response models without prior notice. If this happens, it will always be done in a backward-compatible way, and this documentation will be updated accordingly.

For this reason, it is important that you ensure that your integration is able to gracefully deal with previously undefined response attributes.

 

Last updated on