Webhooks
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.
Please also see the general documentation about the use of push events.
Webhook creation and connection
In order to start receiving push notifications from the Drillster platform, two things need to happen:
- Webhook creation – How should messages be delivered? And which message types should be included?
- Connecting the webhook – What is the scope of the webhook? Should it be used for the entire organization or just for a selection of groups?
Both steps are explained below.
Setting up a new webhook
Users with the appropriate permission will have a “Webhooks” menu option under the “Manage” section in the user console.
If you do not see this menu option but you believe you should have access, please contact us at your support@drillster.com.
The screen lists all of the webhooks that are available to be connected to either the organization as a whole or to specific groups. To create a new webhook, click the “Add” button in the top right-hand corner.
It brings up this form:
The following properties may be populated:
| Property | Description |
|---|---|
| Name | A name for the webhook, only shown internally. This is a mandatory field. |
| Icon image | An optional square icon image to recognize your webhook by. |
| Description | An optional description of your webhook. This is only shown internally. |
| URL | The base target URL. This is a mandatory field, and the URL must start with https://. |
| URL options | Determine how the eventType and eventId are included in the message and which HTTP method is used. See below for more information. |
| Event types | Select which event types should trigger the webhook. You should select at least one option. |
| Authentication | The HTTP calls may optionally require basic auth. Enter the username and password if this is applicable. |
At a minimum, fill in a name for your webhook and a base URL. Save your webhook. You can always change your webhook configuration later by clicking on the appropriate item in the list of webhooks. Webhooks that no longer serve a purpose may be deleted by the user by selecting the “Delete” option from the list.
💡 Good to know
Deleting a webhook will cause the message flow to cease immediately, including any messages for which the delivery was being retried. Changing the webhook URL or authentication details will also have an immediate effect, including for any items that may be in the queue.
Disconnecting a webhook or changing its event types will only affect new messages, and not the messages that may be queued for delivery.
HTTP method and URL template
Each notification contains the message type and a unique event ID. How these fields are included depends on the “Add fields to URL path” settings underneath the target URL field.
POST with body
If neither checkbox is checked, the HTTP call with be made directly to the target URL as a POST, with the eventType and eventId
as payload in the body.
POST with event type in the URL
If only the “Event type” checkbox is checked, the HTTP call will be a POST, with the event type appended to the URL and the
eventId in the body.
PUT with event type and event ID in the URL
If both the “Event type” and “Event ID” checkboxes are checked, the HTTP call will be a PUT, with both fields appended to the URL.
Connecting a webhook
Once a webhook has been created, it still needs to be connected in order for it to become activated. This can be done in one of two ways:
- Connect the webhook to the organization – The webhook will fire if one of the selected events occurs anywhere within the organization.
- Connect the webhook to one or multiple groups – The webhook will fire if one of the selected events occurs within the context of the connected group.
Connecting a webhook to both the organization and one or more groups is also possible, although this may some notifications will be duplicated.
From the list of available webhooks, click on the desired webhook, and then click on the “Connect” button under “Webhook connections”.
Connecting to the organization
The selected webhook may be connected to the organization. Confirm by clicking on “Connect to organization”. The change is effective immediately.
Connecting to groups
To connect a webhook to one or multiple groups, select the groups by typing in a part of the group name and selecting it from a list. Confirm by clicking on “Connect to groups. The change is effective immediately.
Removing connections
If needed, webhook connections may be removed from the list of connections in the webhook sidesheet.
Click on the 
symbol to remove a connection. Note that is there are any messages in the
queue awaiting delivery, the platform will still attempt to deliver them.
Last updated on