Webhook Events

MineOS API supports sending real-time events to an endpoint of your choice so you can create your own automation or workflows, for example: pushing requests to other systems, enriching other systems with data from MineOS, responding to events using MineOS API etc.

Setting Up

Webhook events are setup by clicking the Menu in the lower left corner, selecting Settings -> Developers -> Webhook Events.

Schema

Every event has its own payload, which depends on the event type. All the events share the same basic fields:

{
  "eventId": "123456789abcdefghijklm",
  "eventType": "Webhook",
  "isTest": true
}

Field Name	Type	Description
eventId	String	A unique ID for each event. Should be used for logging. Note: when Mine retries an event, it will have the same eventId.
eventType	String	a string describing the type of event that can be used to determine the schema of the payload.
isTest	Boolean	When true, the event is a test and should be processed in a way that affects production systems/data.

Supported Events

Event Type	Module	Description
Request Created	Requests	A New DSR was created.
System Created	Data Inventory	A System was added to the data inventory.
Employee Inactive	Data Inventory	An employee was changed to Inactive.

Events are sent as HTTP requests of the following form:

POST https://example.com/endpoint HTTP/1.1
X-Mine-Signature: 4r4ClKnSeGWvTGQzMCUcEEK9uF528mvOlN/jtKMQ==
Content-type: application/json

{
  "EventId": "123456789abcdefghijklm",
  "EventType": "TicketCreated",
  "isTest": "false",
  "ticketInfo": ...
}

Reliability

Respond to an event with a 200 OK HTTP status code to acknowledge an event as received. Acknowledged events are not retained and will not be retried.
Response with any other status code, or not respond at all, and Mine will retry sending the event. Retry is done with exponential backoff.

Security

Events are sent over the public internet, so we have implemented multiple security mechanisms to secure this communication. Please review the following section for guidelines on how to process events securely.

Events are sent from the following IP addresses so that you can whitelist them:

34.77.7.236
35.187.97.141
34.76.247.90
34.140.71.114

These IPs are also available through a DNS record: whitelist.portal.saymine.com

To protect your server from unauthorized events, we strongly recommend that you use Hash-based message authentication code (HMAC) signatures. Each event includes a signature calculated using a secret validation key and the event's payload.
By verifying this signature, you confirm that the notification was sent by Mine, and was not modified during transmission. The signature is transmitted in an HTTP header called X-Mine-Signature. The payload is the entire JSON of the event.

To validate the signature, you will need your account’s unique validation key. Each environment has a different validation key.

To debug your implementation, you can use an online HMAC generator: https://www.freeformatter.com/hmac-generator.html

Example code for verifying the signature:

var key = "YOUR VERIFICATION KEY";
var data = "JSON PAYLOAD OF THE EVENT";
 
var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(key));
var rawSignature = hmac.ComputeHash(Encoding.UTF8.GetBytes(data));
var signature = BitConverter.ToString(rawSignature).Replace("-", "").ToLower();

var key = "YOUR VERIFICATION KEY";
var data = "JSON PAYLOAD OF THE EVENT";
 
var crypto = require('crypto');
var signature = crypto.createHmac('SHA256', key).update(data).digest('hex');