Webhooks
Webhooks are where breach notifications get sent
To use the Breach Monitoring Service, it is necessary to setup a Webhook with Enzoic. You will need to specify a URL on your end that will be called with a POST whenever a notification is made. You will also receive a Webhook Key and Webhook Secret which will be passed to your endpoint via basic HTTP authentication.
NOTE: Webhook notifications will be sent from IP address: 52.42.159.171. You may need to update your firewall rules accordingly.
The content of the POST body that will be sent to your webhook for new Breach Monitoring notifications will be a JSON object with the members specified below:
Member | Type | Description |
|---|---|---|
date | date | The date/time (in GMT) that the Exposure was found |
exposureID | string | The ID of the Exposure. This can subsequently be used with the GET Exposure Details API to retrieve additional information about the Exposure. |
username | string | The email address which was exposed. |
usernameHash | string | The SHA-256 hash of the email address exposed. |
plaintextPassword | string | The cleartext version of the password which was found. If the cleartext password was not recoverable, the passwordHash will contain the hashed version of the password, in which case you can hash a password on your end using the algorithm in passwordType and compare it to the passwordHash value to determine if there is a match.
This field will only be present when cleartext credentials API access is enabled. |
passwordHash | string | The hashed value of the password which was found, if the source data contained a password hash rather than the cleartext password.
This field will only be present when cleartext credentials API access is enabled. |
passwordSalt | string | If the password was hashed and a separate salt value is required for this hash type, this is the salt value which was found.
This field will only be present when cleartext credentials API access is enabled. |
passwordType | int | The hash algorithm for the value in the passwordHash field. See the Password Hash Algorithms page for more details.
This field will only be present when cleartext credentials API access is enabled. |
customData | string | This will contain the customData value you provided along with this username when you subscribed it for monitoring, see Breach Monitoring by User. Will not be present if the notification is for a monitored domain. |
An example POST body:
{
"username": "[email protected]",
"usernameHash": "de34a09f96a6677f8a4e0a17545a20e0b60a2f093879c82ed36cff75930d5814",
"date": "2017-01-17T04:51:05.1915231Z"
"exposureID": "583d32144d6db21a908faa11",
"plaintextPassword": "password123!",
"passwordHash": "b7e283a09511d95d6eac86e39e7942c0",
"passwordSalt": "",
"passwordType": 1,
"customData": "corporate_users"
}
For security reasons, you should authenticate calls to your Webhook endpoint. To facilitate this, you will be provided with a Webhook Key and a Webhook Secret when you setup your Webhook with Enzoic. These will be passed as a standard basic authentication HTTP with the Webhook Key as the username and the Webhook Secret as the password. As per the standard, the authentication header passed to your endpoint is constructed as follows:
authorization: basic Base64({Webhook Key}:{Webhook Secret})
Once you have your webhook up and publicly accessible, you can verify all is working using the Webhook Test REST Call using the type=breachAlert query string parameter. This will cause a Breach Monitoring Notification POST to be made to your URL containing test data.
Last modified 2mo ago