1. Help center
  2. Developers Documentation

Event Webhook Reference

Receive JSON events to your endpoint when tickets are created

Events are generated when a new ticket is created and contains all the required information about the ticket. Here is an example event: 

{
"ticketInfo": {
"id": "ABCDEFGHIJKLMNOPQRSTUV",
"type": "Delete",
"source": "MineApp",
"domain": "test.com",
"createdAt": "2021-12-20T17:49:45.7266574Z"
},
"userInfo": {
"name": "Test User",
"email": "testmail@email.com",
"isVerified": true,
"customFields": null
},
"evidence": {
"countryCode": "IL",
"emailEvidence": [
{
"FromAddress": "company@email.com",
"FromDisplayName": "company",
"ReplyTo": [
"company@email.com"
],
"SubjectLine": "We received your order",
"Sent": "2021-12-13T17:49:45.7267409Z"
},
{
"FromAddress": "company@email.com",
"FromDisplayName": "company",
"ReplyTo": [
"company@email.com"
],
"SubjectLine": "Welcome to Acme ",
"Sent": "2021-12-10T17:49:45.7268405Z"
}
],
"evidenceDescription": "FromDisplayName: company FromAddress: company@email.com Subject: We received your order Date: 12/13/2021. \nFromDisplayName: company FromAddress: company@email.com Subject: Welcome to Acme Date: 12/10/2021. ",
"mobileNumber": null,
"state": null,
"address": null
},
"eventId": "123456789abcdefghijklm",
"eventType": "Webhook",
"isTest": true
}
 

JSON object schema

Property

Value

Description

EventId

string

Unique identifier of the event for logging. When the same event is retried the event ID is kept unchanged.

EventType

string

Describes the event type.

IsTest

boolean

True - When testing the integration. The event doesn't describe a real ticket in the system.

False - the event is real and describes an actual ticket in the system.

ticketInfo.id

string

Unique identifier of the ticket in the system.

ticketInfo.type

string

Describes the DSR type. Possible values:

Delete - customer requested deletion

Get - customer requested copy of his data.

ticketInfo.source

string

The source of the ticket (MineApp, email, form API etc)

ticketInfo.domain

string

The domain to which the user sent the request to.

ticketInfo.createdAt

datetime

The creation time of the ticket.

userInfo.name

string

Full name of the requesting user.

userInfo.email

string

Email address of the requesting user.

userInfo.isVerified

boolean

Indicates if the user was verified as the owner of the email address, or not.

userInfo.customFields

dictionary

Optional

A key-value pair collection containing custom fields set through the API. See the API reference for details.

evidence.countryCode

string

Optional

Contains the ISO 3166-1 country code where the user is located.

evidence.emailEvidence

[]

Optional

contains email evidence for the user's interaction with the domain. Fields are: FromAddress, FromDisplayName, ReplyTo, SubjectLine, Sent

evidenceDescription

Optional

concatenated version of evidence.emailEvidence array. Can be used when integrating with a system that has limited capabilities to process array, for example Zapier.

evidence.mobileNumber

Optional

User phone number

evidence.state

string

Optional

User State (for applicable countries)

evidence.address

Optional

User address


The Result Webhook Call

Mine Portal uses the following request when sending webhook events to your endpoint:

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

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

When POSTing events to the target endpoint URL, the portal will wait for a 200 OK response. If no response is received, or the response doesn't indicate success, the event will be retried with exponential backoff along a period of a few days.

The events are retained until 200 OK is received or for a maximum duration of seven days, whatever comes first.

Events will be sent for tickets created only while the integration is enabled. When the integration is disabled, ticket creation events are discarded.


Testing The Integration

We encourage you to test your integration before going live by using the "Test Integration" button. A test event will be sent to the displayed URL.

The test event contains only mock data and does not include any details of a real ticket in your system. This is done to prevent mistakes while testing.

This also means you can use a site like https://webhook.site/ to get a temp endpoint and send a test event there, so you can see it.

Once you are ready to go live, enable the integration and click "Save".


Security

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 payload of the event.

By verifying this signature, you confirm that the notification was sent by Mine Portal, 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 verification key, which can be found on the Webhook setup page.

Example code for verifying the signature:

C#

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();

NodeJS

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');

Best practices for validating events

When performing meaningful actions, such as accessing or deleting user data, make sure to perform the following validations on each event you receive:

  1. Validate that isTest=false
  2. Validate that userInfo.isVerified=true

 Whitelisting IPs

When sending the events, Mine uses the following source IPs so you can whitelist them in your system:

34.77.7.236
35.187.97.141
34.76.247.90
34.140.71.114

 

These IPs can change from time to time, so they are also available by resolving the following DNS record: whitelist.portal.saymine.com