Event receivers

What is an event receiver?

The Drillster event notification service provides a way for external systems to subscribe to certain events that originate in the Drillster system. When these events occur, subscribers are notified via an HTTP call.

The separation of roles

In the context of receiving Push API notification, we have identified two different roles:

1. The technical role is the user that will setup the event receiver with all the settings
2. The manager role is the user that connects to the event receiver and for whom the events are being sent

It is important to mention that without connecting the event receiver to a Group Manager user, the event receiver in itself does not have a value, no events will be sent by Drillster via http.

How to set up an event receiver

When you are using the event receiver, you need to take the following steps in order to integrate the events for the organization.

The “Technical Role” user needs to create the event receiver in the Developer Console. Click on the + sign in the right bottom corner of the screen to set up a new event receiver.

The following fields need to be filled in:

1. In order to ensure the authenticity of the message, we enforce the use of SSL. That means that HTTPS has to be used. HTTP is not supported. The URL is the url to your server.

   We support three templates for the URL, which has to be filled in as one of the following:

   1. https://example.com
   2. https://example.com/{eventType}
   3. https://example.com/{eventType}/{eventId}
      
      

2. The Basic authentication username and password represent the credentials to the server if there are any. The parameters are optional. In case they are filled in, they are encoded in Base64 and sent in the Authorization header in order to ensure the integrity of the message.

3. Select which events you want to receive.

An event receiver can be updated later, so do not worry if you want to change anything, such as supported events.

After you have set up the event receiver you will get a connection link:

This connection link will have to be shared with the group manager of the organization. This can be done via email.

The group manager can click on the link and press the Connect button.

Please also see the general documentation about the use of push events.