Subscriber resolving via an API and target system (like a CRM or Radius Server)

Out of the box, when you start using AbuseHQ, events are assigned to cases based on the IP address. In that default setting, the IP address of the incoming event (or report) is used 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 "Resolvers" that can extract various pieces of metadata and use that data as the Customer Identifier.

One of these resolvers is the API Resolver. This resolver allows you to pass information from the incoming event to a RESTful API endpoint at your end, so your systems can return an appropriate Subscriber Identifier(s) based on that information.

A common use case for the API Resolver is to pass the “IP Address” and “Event Timestamp” to look up the subscriber that was provisioned that IP address was assigned at the time of the event.

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

You may add multiple parameter keys to make it easier for your endpoint and the radius server or CRM system behind that proxy to determine the Subscriber Identifier to return.

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

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 each field's supported and recommended uses.

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.

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 linked to a series of cases and always contains the latest values for each key.

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.

Status codes

AbuseHQ will interpret HTTP Status codes as follows:

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; sometimes, queues can build up in AbuseHQ. And we strongly recommend giving a caching timespan as big as your system allows it to be.

The time this event arrives at AbuseHQ doesn't matter! Let's say it's “2020-11-29T22:00:00Z” and an event includes the IP 10.0.0.2, and the timestamp “2020-11-29T08:00:00Z.” Both 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"}

This result is added to the cache, and every following event with the same IP and timestamp between 02:00 and 12:00 on 11-29 will not be queried again!

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