👋 How can we help you?

CRM Integration Through API - Subscriber Resolver

Integrate with your CRM system using API call during the inbound processing.

API Subscriber Resolver

 

When you just start using AbuseHQ, events are assigned to cases based on the IP address.

In that starting setup, AbuseHQ is configured to use the IP address of the incoming event (or report) as the Customer Identifier.

 

The Inbound Processing workflow allows you to build a decision tree that uses metadata from the event to determine which customer is responsible for an event (e.g. a spam message), and to assign an identifier.

 

AbuseHQ provides a toolbox of "Customer Resolvers" that can extract various metadata and use it as the Customer Identifier.

 

One of these is the API Customer Resolver. This Resolver allows you to pass information from the incoming event to a RESTful API endpoint, and return an appropriate identifier based on that information.

 

A common use case for the API resolver is to pass an IP Address and the Event Timestamp to look up the customer that a dynamic IP address was assigned at the time of the event.

 

How to Configure an API Resolver

  1. Click the Action button in an Inbound Processing workflow item
  1. Select the API Resolver item type
  1. Fill in the name and description.
 
 

Next, provide the endpoint details, including authentication credentials, for your API endpoint:

 
 

You can add multiple parameter keys that your endpoint will use to determine the Customer Identifier to return.

 
⚠️
If your API is behind a firewall, make sure to open the right ports and allow inbound connections from the outgoing IP address listed here: Outgoing IPs
 

What information should an API Customer Resolver Return?

The API Customer Resolver expects certain mandatory fields and can receive some information in addition to the Customer Identifier.

Fields in the Data Response

For a JSON response (our recommended usage), the minimal return for a successful lookup returns just an "id" field that contains the Customer Identifier AbuseHQ should use:

 

Example ID

{ "id" : "ABCDEFGH1234" }

A more verbose Customer Identifier structure with additional metadata can contain the following fields:

 

Example Resolver JSON

{
 "subscriber": {
        "id": "<subscriber_id>",
        "resolver_data": {
            "<subscriber_key1>": "<subscriber_value1>",
            "<subscriber_key2>": "<subscriber_value2>"
        }
    },
    "contract": {
        "id": "<contract_id>",
        "resolver_data": {
            "<contract_key1>": "<contract_value1>",
            "<contract_key2>": "<contract_value2>"
        }
    },
    "result_valid_from": "[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]Z",
    "result_valid_until": "[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]Z"
}
 

Please consult with Abusix support on the supported and recommended uses for each of these fields.

 
⚠️
For string fields in the above structures, we generally accept all characters. However, we recommend you restrict values to alphanumerics with simple punctuation (e.g. '-', '' , '@' etc), and otherwise avoid characters that would require URL-encoding or are unsafe for use in URLs. Avoid using dots ('.'), those will automatically be replaced with underscores ('')
 

Subscriber

The subscriber object must contain the globally unique subscriber id and can optionally contain arbitrary key-value pairs of additional information on that subscriber.

AbuseHQ aggregates this information into a subscriber model that provides the latest values for each key and into the resolver_data field of a case that contains a list of all seen values for each case.

 

Contract

The contract object must contain the globally unique contract id and can optionally contain arbitrary key-value pairs of additional information on that contract.

AbuseHQ aggregates these values into a contract model that is linked to a series of cases and always contains the latest values for each key.

 

HTTP Headers and Status Code

AbuseHQ supports several response formats including JSON and XML. The recommended response format is JSON.

AbuseHQ will send a JSON Request

Accept: application/json

header in its request, and expects a JSON Response

JSON Response

Content-Type: application/json

header in the response.

 

AbuseHQ will interpret HTTP Status codes as follows:

  • 200 OK: Request completed successfully and Customer Identification was provided
  • 404 Not Found: Request completed successfully but no customer was found
 

Any other HTTP status code will be interpreted as a temporary error.

AbuseHQ will queue and retry the request several times for 3 minutes.

After this, the request will be considered unsuccessful and the Inbound Processing flow will continue (with an undefined Customer ID).

We strongly recommend using the timestamp/date in your resolver config attributes because there is no guarantee that events always come in "real-time".

Some reporters send their reports with a delay and sometimes queues can build up in AbuseHQ. And we strongly recommend giving a caching timespan that is as big as your system allows it to be.

 

Example

(The time this event arrives at AbuseHQ doesn't matter! Let's say it's 2020-11-29T22:00:00Z)an event comes in and includes the IP 10.0.0.2 and the timestamp 2020-11-29T08:00:00ZBoth the IP and the timestamp are sent to the resolver.

 

The resolver responds with:

 
{
  "subscriber": {    "id": 111111,    "resolver_data": {      [...]    }  },  "contract": {    [...]  },  "result_valid_from": "2020-11-29T02:00:00",  "result_valid_until": "2020-11-29T12:00:00Z"}
 

Now this result is added to the cache and every following event that comes in with the same IP and a timestamp between 02:00 and 12:00 on 11-29 will not be queried again!

 
⚠️
Your endpoint should generally be capable of understanding URL-encoded field values for Customer Resolver Requests and treat most values as strings.Date, DateTime and Timestamp fields will be formatted as ISO8601 timestamps with the following format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]Z (which is in the UTC timezone).
 
 
 

Learn More

If you want to understand a little bit more about this feature, we recommend the following articles:

Did this answer your question?
😞
😐
🤩