Skip to content

Latest commit

 

History

History
531 lines (414 loc) · 11.7 KB

05-postback-url.md

File metadata and controls

531 lines (414 loc) · 11.7 KB
Raw



Configuring Postback URL Address


Breach Report API provides delivery of breach-related notifications to a user-specified URL address (Postback URL Address). See Notification Data Example for the format of data the API provides.

The Postback URL Address must start with https:// prefix.

The delivered updates provide information on discovered breaches for the domains and URL addresses that are on the watchlist.

You can manage the Postback URL value using the following operations:


Notification Data Format

Show the notification data example. 
{
 "emails": [
  {
   "id": "5e4d7b69d537e9321c432612",
   "emailAddress": "test@test.com",
   "breaches": [
    {
     "breachId": 1,
     "url": "http://Example.org",
     "title": "Example.com",
     "compromisedAccounts": 4540,
     "description": "In August 2019, breached files from a news platform Example.org surfaced on the web. The files included email accounts and passwords. The owners of the website have not made an official statement and the service was shut down shortly after hack. ",
     "breachMonth": 8,
     "breachYear": 2019,
     "breachDataTypes": [
      "email",
      "password"
     ]
    }
   ]
  }
 ],
 "domains": [
  {
   "id": "5e4ee6007c5549457f691cad",
   "domainName": "mydomain.com",
   "emails": [
    {
     "id": "5e4ee6267c5549457f691cae",
     "emailAddress": "test@mydomain.com",
     "breaches": [
      {
       "breachId": 3,
       "url": "https://www.mozilla.org/",
       "title": "MaliceSync.Bforce",
       "compromisedAccounts": 1694274,
       "description": "In April 2019, News Services issued an official statement notifying users on discovering a pattern of suspicious login attempts. Apparently attackers gained access to passwords that have been used on breached websites and attempted to login to user accounts.",
       "breachMonth": 3,
       "breachYear": 2019,
       "breachDataTypes": [
        "email",
        "password"
       ]
      }
     ]
    }
   ]
  }
 ]
}


Get the Postback URL Address

Request URL: {BASE_URL}/api/v1/postback

Request method: GET

Breach Report APi is designed to send notifications to the customer-specified URL address (postback URL).

This call returns the current postback URL (if any) the API uses for notifications.

How to construct the request:

  1. Include the API key in the request header.
  2. Specify your hashed email in the request body.

Request Parameters

Name Type Description
api-key string An API key you can generate on the portal. Include this key in the request header.
email string Email you want to check.

Code Examples

Shell command example. 
curl --location --request GET '{{BASE_URL}}/api/v1/postback' \
--header 'api-key: {{API_KEY}}'
JavaScript code example. 
// Using fetch()
var myHeaders = new Headers();
myHeaders.append("api-key", "{{API_KEY}}");
var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("{{BASE_URL}}/api/v1/postback", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
Python code example. 
# Using requests
import requests
url = "{{BASE_URL}}/api/v1/postback"
payload = {}
headers = {
  'api-key': '{{API_KEY}}'
}
response = requests.request("GET", url, headers=headers, data = payload)
print(response.text.encode('utf8'))
Ruby code example. 
require "uri"
require "net/http"
url = URI("{{BASE_URL}}/api/v1/postback")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Get.new(url)
request["api-key"] = "{{API_KEY}}"
response = http.request(request)
puts response.read_body

Response Examples

Returning the current Postback URL value. 
{
  "status": "success",
  "postbackUrl": "https://example.com:3080/admin/user/test-webhook-url"
}
Name Type Description
status string Result of the operation - success or error.
postbackUrl string Current Postback URL address configuration.
Cannot return the Postback URL when it's not configured. 
{
  "status": "success",
  "postbackUrl": null
}


Set the Postback URL Address

Request URL: {BASE_URL}/api/v1/postback

Request method: POST

Breach Report APi is designed to send notifications to the customer-specified URL address (postback URL).

This request accepts a URL address and sets it as a target for customer-focused Breach Report API notifications.

The Postback URL Address must start with https:// prefix.

If a postback URL value was specified before, the call updates it with the new value.

How to construct the request:

  1. Include the API key in the request header.
  2. Specify the postback URL in the request body.

Request Parameters

Show the parameters.
Name Type Description
api-key string An API key you can generate on the portal. Include this key in the request header.
url string Target postback URL address.

Code Examples

Shell command example. 
curl --location --request POST '{{BASE_URL}}/api/v1/postback' \
--header 'api-key: {{API_KEY}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'url=http://localhost:3080/admin/user/test-webhook-url'
JavaScript code example. 
// Using fetch()
var myHeaders = new Headers();
myHeaders.append("api-key", "{{API_KEY}}");
myHeaders.append("Content-Type", "application/x-www-form-urlencoded");
var urlencoded = new URLSearchParams();
urlencoded.append("url", "https://localhost/test-webhook-url");
var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: urlencoded,
  redirect: 'follow'
};

fetch("{{BASE_URL}}/api/v1/postback", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
Python code example. 
# Using requests
import requests
url = "{{BASE_URL}}/api/v1/postback"
payload = 'url=http%3A//localhost%3A3080/admin/user/test-webhook-url'
headers = {
  'api-key': '{{API_KEY}}',
  'Content-Type': 'application/x-www-form-urlencoded'
}
response = requests.request("POST", url, headers=headers, data = payload)
print(response.text.encode('utf8'))
Ruby code example. 
require "uri"
require "net/http"
url = URI("{{BASE_URL}}/api/v1/postback")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["api-key"] = "{{API_KEY}}"
request["Content-Type"] = "application/x-www-form-urlencoded"
request.body = "url=http%3A//localhost%3A3080/admin/user/test-webhook-url"
response = http.request(request)
puts response.read_body

Request Parameters

Have set the Postback URL successfully. 
{
  "status": "success",
  "postbackUrl": "https://example.com:3080/admin/user/test-webhook-url"
}
Name Type Description
status string Success or error.
postbackUrl [string] The list of credential types that were compromised in the incident.
Cannot set a Postback URL address that is not in the correct format`. 
{
  "status": "error",
  "message": "Postback URL must started with https and be correct"
}


Clear the Postback URL Address

Request URL: {BASE_URL}/api/v1/postback

Request method: DEL

Breach Report APi is designed to send notifications to the customer-specified URL address (Postback URL address).

The request clears the postback URL configuration from your account. As a result of the operation, the API will no longer be able to send you new notifications.

Request Parameters

Show the parameters.
Name Type Description
api-key string An API key you can generate on the portal. Include this key in the request header.

Code Examples

Shell command example. 
curl --location --request DELETE '{{BASE_URL}}/api/v1/postback' \
--header 'api-key: {{API_KEY}}'
JavaScript code example. 
// Using fetch()
var myHeaders = new Headers();
myHeaders.append("api-key", "{{API_KEY}}");

var requestOptions = {
  method: 'DELETE',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("{{BASE_URL}}/api/v1/postback", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
Python code example. 
# Using requests
import requests
url = "{{BASE_URL}}/api/v1/postback"
payload = {}
headers = {
  'api-key': '{{API_KEY}}'
}
response = requests.request("DELETE", url, headers=headers, data = payload)
print(response.text.encode('utf8'))
Ruby code example. 
require "uri"
require "net/http"
url = URI("{{BASE_URL}}/api/v1/postback")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Delete.new(url)
request["api-key"] = "{{API_KEY}}"
response = http.request(request)
puts response.read_body

Response Examples

Cleared the Postback URL configuration successfully. 
{
  "status": "success"
}
Cannot clear a Postback URL value that's not configured. 
{
  "status": "error",
  "message": "Postback urls does not exist"
}