Internal System Integration

Extend the automatic fulfillment process with your own code

The internal system integration allows you to extend the request fulfillment process with your own code.

Each time a request is handled, you can register a call to your API that will handle the request by deleting or fetching a customer's personal information.

The following article explains how the internal system integration works, and how to use it.

Setting up

Access the integration's settings page by going to: Data source -> Internal System 

Type your API's URL that will be called every time a request is processed:

Clicking "Test your integration" will make a test call to this URL so you can make sure it's working.

Once enabled, it now appears as a data source in the request's process step:

Handling deletion requests

A deletion request is handled asynchronously; Mine expects to receive a 200 OK response indicating the deletion process has started. Mine shows the deletion as in progress until receving a second API call marking the process as completed.

If the API fails to return a status code indicating a success, Mine will retry the API cal.

To mark a deletion as completed, use the appropriate API call that is documented here.

Detailed flow:

1. Mine makes an API call to your main endpoint (URL is configured in the UI).
2. Once a 200 OK is received, the request will be switched to "in progress" state.
3. You handle the deletion request by deleting/anonymizing required customer information.
4. Once done, you make an Authenticated API call to POST https://api.portal.saymine.com/api/ticket/WebhookSlimIntegrationStatus to mark the request as completed.
5. The request is switched to "Completed" state.

Handling copy requests

A copy request is handled synchronously; The API call expects to receive a response with a copy of the user's data in the body.

The expected response is a JSON describing user data, where the values can be any arbitrary JSON (object, values, arrays...). There is no schema required to follow.

An example response:

{
  "userProfile": {"firstName":"John", "lastName":"Doe"...},
  "userActivity": [...]
}

Detailed flow:

1. Mine makes an API call to your main endpoint (URL is configured in the UI).
2. You handle the copy request by fetching the customer's personal information.
3. You return a response with 200 OK, and Mine uses the JSON from the body to generate a report for the customer that includes his/her personal information.
4. The request is switched to "Completed" state.

Handling record preview

Before a request is processed, the internal system integration allows previewing records. This is very useful to show records found to be associated with a user, as well as previewing the data.

When implementing the record preview, internal system integration will also be included in "User Search" feature.

To implement the preview flow, you need to configure the preview API endpoint in the integration settings.

The expected response should be a 200 OK with a JSON of the following structure:

{
  "records": [
    {
      "name": "firstRecord",
      "properties": [
        {
          "name": "fieldName",
          "value": "fieldValue"
        },
        {
          "name": "anotherName",
          "value": "anotherValue"
        }
      ]
    },
    {
      "name": "anotherRecord",
      "properties": [
        {
          "name": "fieldName",
          "value": "fieldValue"
        },
        {
          "name": "anotherName",
          "value": "anotherValue"
        }
      ]
    }
  ]
}

Notes:

• You can returns as many records as you want
• You can only return up to 3 properties for each record.
• All property types should be string.

Detailed flow:

1. Mine makes an API call to your Preview endpoint (URL is configured in the UI).
2. You handle the preview request by fetching some of the customer's personal information.
3. You return a response with 200 OK, and Mine uses the JSON from the body to generate a preview.

When handling user search, ticketInfo and evidence fields of the request payload will be missing. They are only available when handling preview (as there is a DSR).

An example user search request can look like this:

{
  "eventId": "LIBEuJtN8EKcN3NsXVZ0xw",
  "eventType": "WebhookSlim",
  "isTest": false,
  "userInfo": {
    "email": "test@gmail.com",
    "isVerified": false
  }
}

Request Body

For a reference with all the fields in the request body, see "Event webhook reference".

Security

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

 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