Enzoic API - Developer Documentation
Visit our website
  • Enzoic Website
  • Getting Started
    • .NET Quick Start
    • Java Quick Start
    • JavaScript Quick Start
    • Ruby Quick Start
    • PHP Quick Start
    • Go Quick Start
    • Python Quick Start
  • Using the Enzoic API
  • Libraries
  • API reference
    • Passwords API
    • Credentials API
      • Hashed Credentials API
      • Cleartext Credentials API
        • Query Passwords for an Email Address
        • Query Passwords for a Domain
        • Query Passwords for a Partial Hash of an Email Address
      • Test Accounts
    • Exposures API
      • Get Exposures for an Email Address
      • Get Exposures for a Domain
      • Get Exposures for All Email Addresses in a Domain
      • Get Exposures by Date
      • Retrieve Details for an Exposure
    • Breach Monitoring API
      • Breach Monitoring by User
        • Add Breach Alert Subscriptions for Users
        • Remove Breach Alert Subscriptions for Users
        • Query Breach Alert Subscriptions for Users
      • Breach Monitoring by Domain
        • Add Breach Alert Subscriptions for Domains
        • Remove Breach Alert Subscriptions for Domains
        • Query Breach Alert Subscriptions for Domains
      • Webhooks
        • Managing Webhooks
          • Register a Webhook
          • Update a Webhook
          • Delete a Webhook
          • Query Registered Webhooks
        • Webhook Test API
    • Identity Breach Monitoring API
      • Monitoring Identities
        • Add Identities to Monitoring
        • Update Monitored Identities
        • Remove an Identity from Monitoring
        • Query Monitored Identities
      • Retrieving Identity Exposures
      • Webhooks
        • Managing Webhooks
          • Register a Webhook
          • Update a Webhook
          • Delete a Webhook
          • Query Registered Webhooks
        • Webhook Test API
    • BIN Monitoring API
      • Monitoring BINs
        • Add Bank Identification Numbers to Monitoring
        • Remove Bank Identification Numbers from Monitoring
        • Query Monitored Bank Identification Numbers
      • Retrieving Exposed Payment Cards
      • Webhooks
        • Managing Webhooks
          • Register a Webhook
          • Update a Webhook
          • Delete a Webhook
          • Query Registered Webhooks
        • Webhook Test API
    • Payment Card Exposures API
      • Check a Card Number for Compromise
    • Account Status APIs
      • Account Status
      • Account Usage
    • Password Hash Algorithms
    • OpenAPI Specification
    • View OpenAPI Spec in Swagger UI
    • Postman Collection of API Examples
  • Password Strength Meter
    • Quick Start
    • Example
Powered by GitBook
On this page
  • Webhook POST Body
  • Webhook Authentication
  • Mutual TLS (mTLS) Authentication (Optional)
  • Setting Up mTLS
  • Payload Encryption (Optional)
  • Testing Your Implementation

Was this helpful?

  1. API reference
  2. Identity Breach Monitoring API

Webhooks

Webhooks are where identity breach notifications get sent

PreviousRetrieving Identity ExposuresNextManaging Webhooks

Last updated 2 months ago

Was this helpful?

To use the Identity 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. This can be done via API using the or by . 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.

Webhook POST Body

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 in the table below.

Additional JSON keys may be added to this payload as we make enhancements to the service, so you must implement JSON parsing for the webhook in a way that will not fail if additional data members are present.

Member
Type
Description

type

string

This will contain piiAlert

tag

string

This will contain the unique tag you specified when adding the identity to be monitored

id

string

This contains the unique Enzoic ID for this monitored identity

date

date

The date/time (in GMT) that the breach/exposure was found

exposureID

string

matchedMonitoredItems

object

An object containing just the monitored values which were matched in this breach. Each value will consist of a JSON object with monitoredValue and foundValue fields, since the formatting of the value found may be different than what is being monitored. See the example on this page for more detail.

rawMatchSource

string

A snippet of text from the breach source showing the content around where the matches were found.

An example POST body:

{
    "type": "piiAlert",
    "tag": "my-tag",
    "id": "57dc11964d6db21300991b78",
    "date": "2023-04-07T07:43:09Z",
    "exposureID": "57ed11964d6db21300991c12",
    "matchedMonitoredItems": {
        "firstName": {
            "foundValue": "Jimmy", 
            "monitoredValue": "JIMMY"
        },
        "lastName": {
            "foundValue": "Dean", 
            "monitoredValue": "DEAN"
        },
        "address1": {
            "foundValue": "2121 Cherrybrook Dr", 
            "monitoredValue": "2121 CHERRYBROOK DR"
        },
        "address2": {
            "foundValue": "Suite 200", 
            "monitoredValue": "SUITE 200"
        },
        "city": {
            "foundValue": "Heisenberg", 
            "monitoredValue": "HEISENBERG"
        },
        "province": {
            "foundValue": "CO", 
            "monitoredValue": "CO"
        },
        "postalCode": {
            "foundValue": "12345", 
            "monitoredValue": "12345"
        },
        "governmentID": {
            "country": "US",
            "foundValue": "232-44-3432",
            "monitoredValue": "232443432",
        },
        "emails": [
            {
                "foundValue": "jimmy@nowhere.com", 
                "monitoredValue": "jimmy@nowhere.com"
            },
        ],
        "creditCards": [
            {
                "foundValue": "4111 1111 1111 1111", 
                "monitoredValue": "4111111111111111"
            },
        ],
        "cryptocurrencyWallets": [
            {
                "foundValue": "0xb794f5ea0ba39494ce839613fffba74279579268",
                "monitoredValue": "0xb794f5ea0ba39494ce839613fffba74279579268"
            },
        ],
        "phoneNumbers": [
            {
                "foundValue": "(555) 323-4433", 
                "monitoredValue": "+15553234433"
            },
        ],
        "secondaryMatchItems": [
            {
                "description": "EIN",
                "foundValue": "12-3123122",
                "monitoredValue": "123123122",
            },
            {
                "description": "Wells Fargo Account Number",
                "foundValue": "900000001",
                "monitoredValue": "900000001",
            },
        ],    
    },
    "rawMatchSource": "Jimmy Dean\n2121 Cherrybrook Dr, Suite 200 Heisenberg, CO 12345\nSSN 232-44-3432\nMobile: (555) 323-4423\njimmy@nowhere.com\nVisa 4111111111111111 03/28 444\nBTC Wallet 0xb794f5ea0ba39494ce839613fffba74279579268 (1.0233 balance)\nEIN: 12-3123122\nWells Fargo Checking - Account #900000001\n"
}

Webhook Authentication

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})

Mutual TLS (mTLS) Authentication (Optional)

If you use an HTTPS endpoint for your webhook's URL, Enzoic will by default confirm that your server certificate is valid prior to posting data by ensuring it is issued by a trusted Certificate Authority and the subject of the certificate matches the webhook domain. This is to help ensure we are communicating with your server and not an unauthorized 3rd party.

Mutual TLS (mTLS) is an optional authentication you may leverage in your webhook to verify that the call actually originated with Enzoic. To take advantage of mTLS, you configure your server to verify Enzoic's client certificate. Enzoic always attempts to send this certificate, so there is no need for any additional configuration on the Enzoic side to enable this functionality.

Setting Up mTLS

To setup mTLS, you will need to do the following:

  1. Configure your web server to require client certificate verification using the certificate from step 1 as the trusted root CA and setting the verification depth to 1.

  2. Verify the client certificate is actually from Enzoic by verifying the subject domain name is webhooks.enzoic.com

Although the client certificate configuration will be specific to your web server, example configurations for NGINX and Apache are below.

NGINX Example Configuration

    server {
        listen       443 ssl;
        
        # ... existing server configuration ...

        # mTLS client certificate configuration 
        ssl_verify_client on;
        ssl_client_certificate /path/to/Enzoic-RootCA-2025.crt;
        ssl_verify_depth 1;

        location / {           
            # check that the client cert's distinguished name matches
            # the expected value, otherwise reject with 403
            if ($ssl_client_s_dn !~ "CN=webhooks.enzoic.com") {
                return 403;
            }
            
            # ... existing location configuration ... #
        }
    }

Apache Example Configuration

Listen 443
<VirtualHost *:443>
    # ... existing SSL configuration for server authentication ...
    SSLVerifyClient require
    SSLCACertificateFile "/path/to/Enzoic-RootCA-2025.crt"
    SSLVerifyDepth 1
</VirtualHost>
<Directory /var/www/>
    Require expr "%{SSL_CLIENT_S_DN_CN} == 'webhooks.enzoic.com'"
    # ... existing directory configuration ...
</Directory>

Payload Encryption (Optional)

Enzoic can optionally encrypt the webhook body with a pre-shared key, using AES encryption. In this case the body of the call will contain a Base64 encoded encrypted version of the JSON payload. It will be necessary to decrypt the received Base64 payload using the pre-shared key. This provides another safeguard to protect the sensitive data contained in the webhook call against unauthorized interception.

Testing Your Implementation

Once you have your webhook up and publicly accessible, you can verify all is working using the Webhook Test REST Call using the type=piiAlert query string parameter. This will cause an Identity Breach Monitoring Notification POST to be made to your URL containing test data.

The ID of the Exposure. This can subsequently be used with the to retrieve additional information about the Exposure.

You can read more about mTLS for webhook security at .

Download the Enzoic root certificate from

to discuss enabling this feature for your webhooks.

Webhooks API
contacting Enzoic Support
https://webhooks.fyi/security/end-to-end-encryption
https://cdn.enzoic.com/certs/Enzoic-RootCA-2025.crt
Contact Enzoic support
GET Exposure Details API