​

Subscriber Resolving via an API and Target System (e.g., CRM or RADIUS Server)

​

API Subscriber Resolver

By default, AbuseHQ assigns events to cases based on the IP address of the incoming event. This IP serves as the Customer Identifier.

The Inbound Processing workflow allows you to build a decision tree that uses event metadata to determine which subscriber (customer) is responsible for an event and assign an identifier accordingly.

AbuseHQ provides a set of Resolvers to extract and evaluate different pieces of metadata. One of the most powerful is the API Resolver.

​

What Is the API Resolver?

The API Resolver allows you to pass information (such as the IP address and event timestamp) from an incoming event to your RESTful API endpoint.
Your backend system (e.g., CRM or RADIUS) then returns the correct Subscriber Identifier.

​

Common Use Case

Look up the subscriber assigned to an IP address at the time of an event using:

• IP address
• Event timestamp

​

How to Configure an API Resolver

To configure an API Resolver in AbuseHQ:

1. Open the Admin Portal.
2. Click Settings in the left menu under AbuseHQ.
3. Select Inbound Processing under Automation.
4. Click on a Resolver in the inbound workflow.
5. In the Type dropdown, choose API Resolver.
6. Fill in the name and description.
7. Provide the API endpoint, authentication credentials, and any required parameters.

⚠️ If your API is behind a firewall, ensure the following outgoing IPs are allowed: 18.193.183.51 52.57.46.129 18.158.191.233

​

What Information Should an API Resolver Return?

The API Resolver expects a JSON response (recommended) with specific fields.

​

✅ Minimal Response

{ "id": "ABCDEFGH1234" }

​

Full Resolver JSON Example

{
  "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-DDTHH:mm:ssZ",
  "result_valid_until": "YYYY-MM-DDTHH:mm:ssZ"
}

Please consult with Abusix support on each field’s supported and recommended uses.

⚠️ 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 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 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.

​

Status codes

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 theInbound 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. We strongly recommend giving a caching timespan as big as your system allows it to be.

​

Example

An event comes in and includes the IP 10.0.0.2 and the timestamp 2020-11-29T08:00:00Z:

_⚠️ (The time this event arrives at AbuseHQ doesn’t matter! Let’s say it’s 2020-11-29T22: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:00Z",
  "result_valid_until": "2020-11-29T12:00:00Z"
}

NOTE:

"result_valid_from": "[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]Z",
"result_valid_until": "[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]Z"

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!