Alerts and Alert API
Overview
Alerts are designed to notify you when recent leads or signups have an increase in risk. If items are added to blacklists matching your vetting data, E-HAWK will automatically send an email alert so you can quickly review the user and take any necessary actions. Alert Emails are sent every six hours with all alerts during that time frame. If you prefer API calls for alerts, use the Alert API and call anytime you wants updates.
Settings
Alert settings are configured in the Portal. Select alert data types and a scoring threshold to filters only high impact score changes. Items in your scoring profile that exceed the alert threshold will create alerts. In addition, recent alerts can be viewed in the Portal Alert tab.
In the settings area you can configure email addresses for Alert notices, toggle between Alert Type of (Email or API), set score threshold, and turn on/off data points to monitor.
Data and Format
Alerts contain the following data and are delivered in JSON format.
| alert_id | The ID of the Alert |
| transaction_id | transaction ID of the API call |
| type | The type that hit the alert such as IP, Email, Phone, etc |
| value | The value that hit the alert |
| reason | The reason hit for the alert such as Phishing. |
| transaction_score | The Risk Score of the original API call |
| alert_score_impact | the change or impact of the new risk hit based on your scoring profile |
| estimated_new_score | An estimate of the new risk score based on the new risk hit |
| username | username value sent in API call |
| lead_id | lead_id value sent in API call |
| transaction_fingerprint | The fingerprint sent in API call |
| transaction_date | The timestamp of the API call (UTC) |
| alert_date | The timestamp the Alert was created (UTC) |
Email Alerts
Email Alerts are sent every six hours to your configured Alert email addresses and contain a list of all issues during that period. The emails show data for each Alert and contain JSON data at the end for back-end processing. As an example:
The following transactions(s) have been tagged with new information. You may want to review or revet the user(s) as their risk score has changed. At the bottom of this email are alerts in JSON format for back-end processing.
alert_id: 12345
transaction_id: 56fbed88a7c018
type: ip
value: 10.1.1.1
reason: Phishing
transaction_score: -38
alert_score_impact: -70
estimated_new_score: -108
username: user1234
campaign_id: campaign
lead_source: lead source
lead_id: abcde
transaction_fingerprint: fb713c209
transaction_date: 2020-04-10 06:00:00 (UTC)
alert_date: 2020-04-10 06:25:00 (UTC)
-- JSON DATA START --
[{"alert_id":"12345", "transaction_id":"56fbed88a7c018", "type":"ip", "value":"10.1.1.1", "reason":"Phishing", "transaction_score":"-38", "alert_score_impact":"-70", "estimated_new_score":"-108", "username":"user1234", "campaign_id":"campaign", "lead_source":"lead source", "lead_id":"abcde", "transaction_fingerprint":"fb713c209" "transaction_date":"2023-11-10 06:00:00", "alert_date":"2023-11-10 06:25:00"}]
-- JSON DATA END --
Endpoint (6.4)
https://feed-api.ehawk.net/alert/
The API accepts both HTTPS POST and HTTPS GET.
For GET use the format:
https://feed-api.ehawk.net/alert/function/?keyword=value
When using POST, make sure to have Content-Type: application/x-www-form-urlencoded
CURL POST API call example:
curl -X POST -H Content-Type:application/x-www-form-urlencoded -d 'apikey=your_apikey' https://feed-api.ehawk.net/alert/function/
Functions
Select the action to take using function values:
list get all new Alerts, and mark in system as "sent"list24 get every Alert within the last 24 hours. Does not mark any as "sent". Should be used for QA and testing API function only!
Use the list call to get unread alerts. As an example, using GET to see all new alerts:
https://feed-api.ehawk.net/alert/list?apikey=your_apikey
| Keyword | Value and Format |
|---|---|
| apikey | Your Vetting API KEY (required) |
| id | When calling list you can add optional id=alert_id. This will return up to 500 Alerts, starting at the alert_id. The option returns all alerts and marks any unsent as sent. Increase the alert_id for paging. Use this call when checking if your backend has received all alerts starting at an alert_id.https://feed-api.ehawk.net/alert/list?apikey=your_apikey&id=alert_id |
JSON Response
The response will be a JSON string with each Alert in a new sub JSON string. The Alert JSON contains the Transaction ID and all the data for the Alert. As an example:
{
"response": [
{
"alert_id": "12345",
"transaction_id": "56fbed88a7c018",
"type": "ip",
"value": "10.1.1.1",
"reason": "Phishing",
"transaction_score": "-38",
"alert_score_impact": "-70",
"estimated_new_score": "-108",
"username": "user1234",
"transaction_fingerprint": "fb713c209",
"transaction_date": "2016-04-10 06:00:00 (UTC)",
"alert_date": "2016-06-10 10:00:00 (UTC)"
}
],
"status": 200
}
Status Codes
| Status | Response |
|---|---|
| 200 | OK (no errors) |
| 403 | Alert Type is set to Email in the Portal. Change to API. |
| 502 | Invalid APIKEY or URL |
| -6 | IP not in ACL |