Skip to main content
API docs by Redocly

Generator Labs API (4.0)

Generator Labs Support: support@generatorlabs.com Terms of Service

The Generator Labs API is a RESTful web service API that lets customers manage their RBL monitoring hosts, certificate monitoring, contacts, and retrieve listing information.

Version 4.0 introduces a reorganized endpoint structure with proper REST verbs and resource grouping for improved consistency and usability.

Key Changes in v4.0

  • Reorganized endpoints under /rbl/, /cert/, and /contact/ resource groups
  • Proper REST verbs (POST for create, PUT for update, DELETE for delete)
  • Simplified endpoint paths with resource-based URLs
  • Backward compatible authentication and response formats

Rate Limiting

API requests are subject to two levels of rate limiting:

  • Hourly limit: 1,000 requests per hour per API application
  • Per-second limit: varies by endpoint (100 RPS for reads, 50 RPS for writes, 20 RPS for manual checks)

Rate limit information is provided on every response using the following headers:

  • RateLimit-Limit: active policies, e.g. 1000;w=3600, 100;w=1 (1,000/hour and 100/second)
  • RateLimit-Remaining: requests remaining in the most restrictive active window
  • RateLimit-Reset: seconds until the most restrictive window resets

When rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

Error Responses

All error responses follow a consistent format using status_code and status_message:

{
  "status_code": 500,
  "status_message": "A description of the error."
}

Status Codes:

  • 200 - Success
  • 401 - Authentication failed
  • 403 - IP address restriction
  • 429 - Rate limit exceeded
  • 500 - Server error or validation failure

PHP SDK

The PHP SDK can be installed via composer:

composer require generatorlabs/sdk

Or the source code can be downloaded directly from the GitHub repository.

The PHP SDK requires PHP >= 8.1 and the PHP JSON extension.

Node.js SDK

The Node.js SDK can be installed via npm:

npm install generatorlabs

Or the source code can be downloaded directly from the GitHub repository.

The Node.js SDK requires Node.js >= 18.0.

Python SDK

The Python SDK can be installed via pip:

pip install generatorlabs

Or the source code can be downloaded directly from the GitHub repository.

The Python SDK supports Python >= 3.8.

Go SDK

The Go SDK can be installed via go get:

go get github.com/generator-labs/go-sdk

Or the source code can be downloaded directly from the GitHub repository.

The Go SDK requires Go >= 1.21.

Ruby SDK

The Ruby SDK can be installed via gem:

gem install generatorlabs

Or the source code can be downloaded directly from the GitHub repository.

The Ruby SDK requires Ruby >= 3.0.

Check

Start manual, real-time checks against hosts on your account or one-off IP addresses/domains.

Start Check

Starts a manual check for a provided Host.

This process is asynchronous, in that it returns right away, returning a check id that you may use to poll for subsequent updates. This is done because a full RBL check may take some time to process, and this avoids blocking the API response.

Rate limit: 20 requests/second

Authorizations:
basicAuth
Request Body schema: application/x-www-form-urlencoded
required
host
required
string^(?:(?:[0-9]{1,3}\.){3}[0-9]{1,3}|[a-zA-Z0-9]...

The host value; either an IP address, domain name, or host SID (to use an existing host).

callback
string <uri>

An HTTP callback URL that we will post to once the check request completes.

details
boolean
Default: false

A flag indicating if the RBL details should be returned with the response.

Responses

Callbacks

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/rbl/check/start.json \
    -u 'your_account_sid:your_auth_token' \
    -d host='10.10.10.11' \
    -d callback='https://your.website.com/callback.php' \
    -d details=true

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Check started successfully.",
  • "data": {
    }
}

Callback payload samples

Callback
POST: {$request.body#/callback}
Content type
application/json
{
  • "event_sid": "TA9dbf5e2f7e924418a6d6b483a584adcf",
  • "event_type": "rbl.host.check.completed",
  • "event_date": "2025-12-22T23:43:52+00:00",
  • "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
  • "host": {
    },
  • "listed": true,
  • "total": 1,
  • "details": [
    ]
}

Check Status

Gets the status of a previously started manual check.

You can use the check id returned from /4.0/rbl/check/start to poll for check status in real-time.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^PP[0-9a-f]{64}$
Example: PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a

Check id returned from /check/start.

query Parameters
details
boolean
Default: false

A flag indicating if the RBL details should be returned with the response.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/rbl/check/status/{id}.json?details=true \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Check status retrieved successfully.",
  • "data": {
    }
}

Listings

Retrieve all hosts currently listed on one or more RBLs.

Listings

Return a full list of all the hosts that are currently listed on one or more data sources.

This data mirrors the response returned by the /4.0/hosts API request. The only difference, is the /4.0/listings request only returns hosts that are currently listed, instead of all hosts.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/rbl/listings.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Listings",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "total_listed": 1,
  • "data": [
    ]
}

Hosts

Manage hosts configured on your account for RBL monitoring.

List Hosts

Returns a full list of hosts configured on your account.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/rbl/hosts.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Hosts",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 2,
  • "total_listed": 1,
  • "data": [
    ]
}

Create Host

Create a new host on your account.

When using the ip_range host type, or when adding hosts by subnet, multiple hosts may be created and returned in the data response object.

Rate limit: 50 requests/second

Authorizations:
basicAuth
Request Body schema: application/x-www-form-urlencoded
required
host
required
string^(?:(?:[0-9]{1,3}\.){3}[0-9]{1,3}(?:\/[0-9]{1...

Host value (IP/domain/subnet) based on type.

name
required
string [ 1 .. 255 ] characters

Label for the Host.

profile
required
string^RP[0-9a-f]{32}$

Monitoring Profile id to use on this Host.

contact_group
required
string

Comma-separated list of one or more Contact Group SIDs to use for this Host.

tags
string

Comma-separated list of tags to assign to the host.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/rbl/hosts.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My New Host' \
    -d host='10.10.10.11' \
    -d profile='RP9f8e7d6c5b4a3210fedcba0987654321' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234' \
    -d tags='production,web'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Host added successfully.",
  • "data": [
    ]
}

Get Host

Returns details for an individual host.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^HT[0-9a-f]{32}$
Example: HT1a2b3c4d5e6f7890abcdef1234567890

Unique Host SID.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/rbl/hosts/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Hosts",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "total_listed": 1,
  • "data": [
    ]
}

Update Host

Updates an existing host on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^HT[0-9a-f]{32}$
Example: HT1a2b3c4d5e6f7890abcdef1234567890

Unique Host SID.

Request Body schema: application/x-www-form-urlencoded
optional
name
string [ 1 .. 255 ] characters

The label for this Host.

profile
string^RP[0-9a-f]{32}$

The unique SID of the Monitoring Profile to use for this Host.

contact_group
string

Comma-separated list of one or more Contact Group SIDs to use for this Host.

tags
string

Comma-separated list of tags to assign to the host.

Responses

Request samples 

curl -X PUT https://api.generatorlabs.com/4.0/rbl/hosts/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My Updated Host' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234' \
    -d tags='production,web'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Host updated successfully."
}

Delete Host

Deletes an existing host on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^HT[0-9a-f]{32}$
Example: HT1a2b3c4d5e6f7890abcdef1234567890

Unique Host SID.

Responses

Request samples 

curl -X DELETE https://api.generatorlabs.com/4.0/rbl/hosts/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Host deleted successfully."
}

Pause Host

Pauses a Host, which temporarily stops all checks on this Host.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^HT[0-9a-f]{32}$
Example: HT1a2b3c4d5e6f7890abcdef1234567890

Unique Host SID.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/rbl/hosts/{id}/pause.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Host paused successfully."
}

Re-Activate Host

Re-activates a Host after it was paused. We will resume processing checks on this host.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^HT[0-9a-f]{32}$
Example: HT1a2b3c4d5e6f7890abcdef1234567890

Unique Host SID.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/rbl/hosts/{id}/resume.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Host activated successfully."
}

Monitoring Profiles

Manage monitoring profiles that control which RBLs are checked for hosts.

Note: These features are only available to customers on a paid plan.

List Profiles

Returns a full list of monitoring profiles configured on your account.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/rbl/profiles.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Monitoring Profiles",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Create Profile

Create a new monitoring profile on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
Request Body schema: application/x-www-form-urlencoded
required
name
required
string [ 1 .. 255 ] characters

Label for the Profile.

entries
string

Comma-separated list of RBL SIDs to include in this profile.

is_default
boolean

Set this profile as the account default.

frequency
required
string
Enum: "1_hour" "2_hours" "3_hours" "6_hours" "12_hours" "24_hours" "48_hours" "weekly" "2_weeks"

Check frequency interval.

sync_method
required
string
Enum: "stay_in_sync" "use_my_selections"

RBL sync method. Automatically set to 'use_my_selections' when entries are provided.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/rbl/profiles.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My Custom Profile' \
    -d entries='RB1234567890abcdef1234567890abcdef,RB0987654321fedcba0987654321fedcba'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Monitoring Profile added successfully.",
  • "data": {
    }
}

Get Profile

Returns details for an individual monitoring profile.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RP[0-9a-f]{32}$
Example: RP9f8e7d6c5b4a3210fedcba0987654321

Unique Profile SID.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/rbl/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Monitoring Profiles",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Update Profile

Updates an existing monitoring profile on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RP[0-9a-f]{32}$
Example: RP9f8e7d6c5b4a3210fedcba0987654321

Unique Profile SID.

Request Body schema: application/x-www-form-urlencoded
optional
name
string [ 1 .. 255 ] characters

The label for this Profile.

entries
string

Comma-separated list of RBL SIDs to include in this profile.

is_default
boolean

Set this profile as the account default.

frequency
string
Enum: "1_hour" "2_hours" "3_hours" "6_hours" "12_hours" "24_hours" "48_hours" "weekly" "2_weeks"

Check frequency interval.

sync_method
string
Enum: "stay_in_sync" "use_my_selections"

RBL sync method. Automatically set to 'use_my_selections' when entries are provided.

Responses

Request samples 

curl -X PUT https://api.generatorlabs.com/4.0/rbl/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='Updated Profile Name' \
    -d entries='RB1234567890abcdef1234567890abcdef,RB0987654321fedcba0987654321fedcba'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Monitoring Profile updated successfully."
}

Delete Profile

Deletes an existing monitoring profile on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RP[0-9a-f]{32}$
Example: RP9f8e7d6c5b4a3210fedcba0987654321

Unique Profile SID.

Responses

Request samples 

curl -X DELETE https://api.generatorlabs.com/4.0/rbl/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Monitoring profile deleted successfully."
}

Sources

Retrieve all active RBL sources on the system, including custom RBLs you've added.

Note: These features are only available to customers on a paid plan.

List Sources

Returns a full list of all active RBL sources on the system, including custom RBLs you've added.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/rbl/sources.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Data Sources",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": []
}

Create Source

Create a new custom RBL source on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
Request Body schema: application/x-www-form-urlencoded
required
host
required
string^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9](?:\...

Hostname of the RBL server.

type
required
string
Enum: "rbl" "rbl_v6" "uribl"

The type of the data source.

custom_codes
string

Comma-separated list of custom DNS response codes (e.g. 127.0.0.2,127.0.0.3). Used to define which response codes indicate a listing.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/rbl/sources.json \
    -u 'your_account_sid:your_auth_token' \
    -d host='custom.rbl.example.com' \
    -d type='rbl' \
    -d custom_codes='127.0.0.2,127.0.0.3'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Custom RBL added successfully.",
  • "data": {
    }
}

Get Source

Returns details for an individual RBL source.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RB[0-9a-f]{32}$
Example: RB1234567890abcdef1234567890abcdef

Unique RBL SID.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/rbl/sources/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Data Sources",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": []
}

Update Source

Updates an existing RBL source on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RB[0-9a-f]{32}$
Example: RB1234567890abcdef1234567890abcdef

Unique RBL SID.

Request Body schema: application/x-www-form-urlencoded
optional
host
string^[a-zA-Z0-9][a-zA-Z0-9-]{0,61}[a-zA-Z0-9](?:\...

The hostname of the RBL server.

type
string
Enum: "rbl" "rbl_v6" "uribl"

The type of the data source.

custom_codes
string

Comma-separated list of custom DNS response codes (e.g. 127.0.0.2,127.0.0.3). Used to define which response codes indicate a listing.

Responses

Request samples 

curl -X PUT https://api.generatorlabs.com/4.0/rbl/sources/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d host='updated.rbl.example.com' \
    -d custom_codes='127.0.0.2,127.0.0.3'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Custom RBL updated successfully."
}

Delete Source

Deletes an existing RBL source on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RB[0-9a-f]{32}$
Example: RB1234567890abcdef1234567890abcdef

Unique RBL SID.

Responses

Request samples 

curl -X DELETE https://api.generatorlabs.com/4.0/rbl/sources/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Custom RBL deleted successfully."
}

Pause Source

Pauses an RBL source, temporarily excluding it from all checks.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RB[0-9a-f]{32}$
Example: RB1234567890abcdef1234567890abcdef

Unique RBL SID.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/rbl/sources/{id}/pause.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Custom RBL paused successfully."
}

Resume Source

Resumes a paused RBL source, re-enabling it in all checks.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^RB[0-9a-f]{32}$
Example: RB1234567890abcdef1234567890abcdef

Unique RBL SID.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/rbl/sources/{id}/resume.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Custom RBL activated successfully."
}

Errors

Retrieve active certificate errors across all monitors.

List Certificate Errors

Returns a list of currently active certificate errors across all monitors.

Rate limit: 100 requests/second

Authorizations:
basicAuth

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/cert/errors.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Errors",
  • "total_errors": 3,
  • "data": [
    ]
}

Monitors

Manage certificate monitors configured on your account for TLS/SSL certificate monitoring.

List Certificate Monitors

Returns a full list of certificate monitors configured on your account.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/cert/monitors.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitors",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 2,
  • "data": [
    ]
}

Create Certificate Monitor

Create a new certificate monitor on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
Request Body schema: application/x-www-form-urlencoded
required
hostname
required
string

The hostname to monitor for certificate status.

protocol
required
string
Enum: "https" "smtps" "smtp" "imaps" "imap" "pops" "pop" "lmtp" "ftps" "ftp" "ldaps" "ldap" "mysql" "postgresql" "sips"

The protocol to use when checking the certificate.

name
required
string [ 1 .. 255 ] characters

Label for the Certificate Monitor.

profile
required
string^CP[0-9a-f]{32}$

Certificate Monitoring Profile id to use on this monitor.

contact_group
required
string

Comma-separated list of Contact Group ids to use.

tags
string

Comma-separated list of tags for organization.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/cert/monitors.json \
    -u 'your_account_sid:your_auth_token' \
    -d hostname='example.com' \
    -d protocol='https' \
    -d name='My SSL Certificate' \
    -d profile='CP15d4e891d784977cacbfcbb00c48f133' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234' \
    -d tags='production,web,ssl'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitor added successfully.",
  • "data": {
    }
}

Get Certificate Monitor

Returns details for an individual certificate monitor.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CM[0-9a-f]{32}$
Example: CM62944aeeee2b46d7a28221164f38976a

Unique Certificate Monitor SID.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/cert/monitors/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitors",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Update Certificate Monitor

Updates an existing certificate monitor on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CM[0-9a-f]{32}$
Example: CM62944aeeee2b46d7a28221164f38976a

Unique Certificate Monitor SID.

Request Body schema: application/x-www-form-urlencoded
optional
name
string [ 1 .. 255 ] characters

The label for this Certificate Monitor.

profile
string^CP[0-9a-f]{32}$

The unique SID of the Certificate Monitoring Profile to use for this monitor.

contact_group
string

Comma-separated list of one or more Contact Group SIDs to use for this monitor.

tags
string

Comma-separated list of tags for organization.

Responses

Request samples 

curl -X PUT https://api.generatorlabs.com/4.0/cert/monitors/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My Updated Monitor' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234' \
    -d tags='production,web,ssl'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitor updated successfully."
}

Delete Certificate Monitor

Deletes an existing certificate monitor on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CM[0-9a-f]{32}$
Example: CM62944aeeee2b46d7a28221164f38976a

Unique Certificate Monitor SID.

Responses

Request samples 

curl -X DELETE https://api.generatorlabs.com/4.0/cert/monitors/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitor deleted successfully."
}

Pause Certificate Monitor

Pauses a certificate monitor on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CM[0-9a-f]{32}$
Example: CM4f3e2d1c0b9a8776655443322110fedc

Unique Certificate Monitor SID.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/cert/monitors/{id}/pause.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitor paused successfully."
}

Resume Certificate Monitor

Resumes a paused certificate monitor on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CM[0-9a-f]{32}$
Example: CM4f3e2d1c0b9a8776655443322110fedc

Unique Certificate Monitor SID.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/cert/monitors/{id}/resume.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Monitor activated successfully."
}

Cert Profiles

Manage certificate monitoring profiles that control validation rules and alert thresholds.

List Certificate Profiles

Returns a full list of certificate monitoring profiles configured on your account.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/cert/profiles.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Profiles",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 2,
  • "data": [
    ]
}

Create Certificate Profile

Create a new certificate monitoring profile on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
Request Body schema: application/x-www-form-urlencoded
required
name
required
string [ 1 .. 255 ] characters

Label for the Certificate Profile.

expiration_thresholds
string

Comma-separated list of days before expiration to send alerts (e.g., '30,14,7').

alert_on_expiration
boolean
Default: true

Send alerts when certificate is expiring based on thresholds.

alert_on_name_mismatch
boolean
Default: true

Send alerts when certificate hostname doesn't match the requested hostname.

alert_on_ca_failure
boolean
Default: true

Send alerts when certificate authority validation fails.

alert_on_connection_failure
boolean
Default: true

Send alerts when unable to establish a connection to check the certificate.

alert_on_caa_failure
boolean
Default: false

Send alerts when CAA (Certificate Authority Authorization) record validation fails.

alert_on_misconfigurations
boolean
Default: true

Send alerts on certificate misconfigurations.

alert_on_changes
boolean
Default: true

Send alerts when certificate changes are detected.

is_default
boolean

Set this profile as the account default.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/cert/profiles.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My Certificate Profile' \
    -d expiration_thresholds='30,14,7' \
    -d alert_on_expiration=true \
    -d alert_on_name_mismatch=true \
    -d alert_on_misconfigurations=true \
    -d alert_on_changes=true

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Profile added successfully.",
  • "data": {
    }
}

Get Certificate Profile

Returns details for an individual certificate monitoring profile.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CP[0-9a-f]{32}$
Example: CP79b597e61a984a35b5eb7dcdbc3de53c

Unique Certificate Profile SID.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/cert/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Profiles",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Update Certificate Profile

Updates an existing certificate monitoring profile on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CP[0-9a-f]{32}$
Example: CP79b597e61a984a35b5eb7dcdbc3de53c

Unique Certificate Profile SID.

Request Body schema: application/x-www-form-urlencoded
optional
name
string [ 1 .. 255 ] characters

The label for this Certificate Profile.

expiration_thresholds
string

Comma-separated list of days before expiration to send alerts (e.g., '30,14,7').

alert_on_expiration
boolean

Send alerts when certificate is expiring based on thresholds.

alert_on_name_mismatch
boolean

Send alerts when certificate hostname doesn't match the requested hostname.

alert_on_ca_failure
boolean

Send alerts when certificate authority validation fails.

alert_on_connection_failure
boolean

Send alerts when unable to establish a connection to check the certificate.

alert_on_caa_failure
boolean

Send alerts when CAA (Certificate Authority Authorization) record validation fails.

alert_on_misconfigurations
boolean

Send alerts on certificate misconfigurations.

alert_on_changes
boolean

Send alerts when certificate changes are detected.

is_default
boolean

Set this profile as the account default.

Responses

Request samples 

curl -X PUT https://api.generatorlabs.com/4.0/cert/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='My Updated Profile' \
    -d expiration_thresholds='45,14,7' \
    -d alert_on_misconfigurations=true \
    -d alert_on_changes=true

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Profile updated successfully."
}

Delete Certificate Profile

Deletes an existing certificate monitoring profile on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CP[0-9a-f]{32}$
Example: CP79b597e61a984a35b5eb7dcdbc3de53c

Unique Certificate Profile SID.

Responses

Request samples 

curl -X DELETE https://api.generatorlabs.com/4.0/cert/profiles/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Certificate Profile deleted successfully."
}

Contacts

Manage individual contacts configured on your account.

Get a List of Contacts

Returns a full list of contacts on your account.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/contact/contacts.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contacts",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 2,
  • "data": [
    ]
}

Create Contact

Create a new contact on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
Request Body schema: application/x-www-form-urlencoded
required
contact
required
string

The contact value based on the type.

type
required
string
Enum: "email" "sms" "pushover" "pagerduty" "slack" "datadog" "discord" "telegram" "endpoint" "aws-sns" "aws-cloudwatch"

Contact type (email, sms, slack, webhook, etc.)

schedule
required
string
Deprecated
Enum: "every_check" "start_and_end" "while_listed"

The notification schedule. This field is being phased out and will be removed in a future API version.

contact_group
required
string

Comma-separated list of Contact Group SIDs to assign to this Contact. Example: "CONTACTGROUPsid1,CONTACTGROUPsid2"

args
object or null

Additional configuration for the contact type (e.g. endpoint URL, Datadog API key). Required for some contact types.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/contact/contacts.json \
    -u 'your_account_sid:your_auth_token' \
    -d contact='admin@example.com' \
    -d type='email' \
    -d schedule='every_check' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact added successfully.",
  • "data": {
    }
}

Get Contact

Returns the details for a single contact.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COabcdef1234567890abcdef1234567890

The unique SID of the Contact.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/contact/contacts/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contacts",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Update Contact

Updates an existing contact on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COabcdef1234567890abcdef1234567890

Unique Contact SID.

Request Body schema: application/x-www-form-urlencoded
optional
contact
string

The contact value based on the type.

schedule
string
Deprecated
Enum: "every_check" "start_and_end" "while_listed"

The notification schedule. This field is being phased out and will be removed in a future API version.

contact_group
string

Comma-separated list of Contact Group SIDs to assign to this Contact. Example: "CONTACTGROUPsid1,CONTACTGROUPsid2"

Responses

Request samples 

curl -X PUT https://api.generatorlabs.com/4.0/contact/contacts/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d contact='updated@example.com' \
    -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact updated successfully."
}

Delete Contact

Deletes an existing contact on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COabcdef1234567890abcdef1234567890

Unique Contact SID.

Responses

Request samples 

curl -X DELETE https://api.generatorlabs.com/4.0/contact/contacts/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact deleted successfully."
}

Pause Contact

Pause a contact. This will temporarily stop notifications to this contact.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COd3dca251d33135e0a518d7c49b89dc61

The unique SID of the Contact.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/pause.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact paused successfully."
}

Re-Activate Contact

Re-activate a contact after it was paused. We will resume sending notifications to this contact.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COd3dca251d33135e0a518d7c49b89dc61

The unique SID of the Contact.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/resume.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact activated successfully."
}

Resend Confirmation

Resends the authorization confirmation to the specified contact. The contact must be in 'pending' status.

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COd3dca251d33135e0a518d7c49b89dc61

The unique SID of the Contact.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/resend.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact authorization re-sent successfully."
}

Confirm Contact

Confirms a pending contact using a confirmation code.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CO[0-9a-f]{32}$
Example: COabcdef1234567890abcdef1234567890

The unique SID of the Contact.

Request Body schema: application/x-www-form-urlencoded
required
authcode
required
string

Confirmation token delivered to the Contact.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/confirm.json \
    -d authcode='3Kx3se' \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact authorized successfully."
}

Contact Groups

Manage contact groups configured on your account.

Get a List of Contact Groups

Returns a full list of contact groups on your account.

The is_default flag defines which contact group is marked as default. The default contact group is used on new hosts and contacts when a contact group ID is omitted.

Only one contact group can be marked a default. If you add a new contact group, or update an existing contact group, and set is_default to 1, then any existing default contact group will no longer be set as default.

Rate limit: 100 requests/second

Authorizations:
basicAuth
query Parameters
page
integer >= 1
Default: 1

The current page number.

page_size
integer >= 1
Default: 100

Entries per page.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/contact/groups.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact Groups",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Create Contact Group

Create a new contact group on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
Request Body schema: application/x-www-form-urlencoded
required
name
required
string [ 1 .. 255 ] characters

Name for the contact group.

is_default
boolean

Set this Contact Group as the default.

Responses

Request samples 

curl -X POST https://api.generatorlabs.com/4.0/contact/groups.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='Primary Contacts'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact group added successfully.",
  • "data": {
    }
}

Get Contact Group

Return details for a single Contact Group, based on the SID passed.

Rate limit: 100 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CG[0-9a-f]{32}$
Example: CG4f3e2d1c0b9a8776655443322110fedc

The unique SID of the Contact Group.

Responses

Request samples 

curl -G https://api.generatorlabs.com/4.0/contact/groups/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact Groups",
  • "page": 1,
  • "page_size": 100,
  • "total_pages": 1,
  • "total": 1,
  • "data": [
    ]
}

Update Contact Group

Updates an existing contact group on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CG[0-9a-f]{32}$
Example: CG4f3e2d1c0b9a8776655443322110fedc

Unique Contact Group SID.

Request Body schema: application/x-www-form-urlencoded
optional
name
string [ 1 .. 255 ] characters

Name for the contact group.

is_default
boolean

Set this Contact Group as the default.

Responses

Request samples 

curl -X PUT https://api.generatorlabs.com/4.0/contact/groups/{id}.json \
    -u 'your_account_sid:your_auth_token' \
    -d name='Updated Contact Group'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact group updated successfully."
}

Delete Contact Group

Deletes an existing contact group on your account.

Rate limit: 50 requests/second

Authorizations:
basicAuth
path Parameters
id
required
string^CG[0-9a-f]{32}$
Example: CG4f3e2d1c0b9a8776655443322110fedc

Unique Contact Group SID.

Responses

Request samples 

curl -X DELETE https://api.generatorlabs.com/4.0/contact/groups/{id}.json \
    -u 'your_account_sid:your_auth_token'

Response samples

Content type
application/json
{
  • "status_code": 200,
  • "status_message": "Contact Group deleted successfully."
}

Webhook Verification

All webhook requests include an X-Webhook-Signature header that can optionally be used to verify the authenticity of the request. Each webhook endpoint has a unique Signing Secret, available in the Portal under Dev > Webhooks > Edit.

The header format is:

X-Webhook-Signature: t=1738900000,v1=5257a869...

Where t is the Unix timestamp and v1 is the HMAC-SHA256 signature computed over {t}.{body} using the webhook's Signing Secret.

To verify a webhook request:

  1. Extract t and v1 from the X-Webhook-Signature header
  2. Compute HMAC-SHA256(signing_secret, "{t}.{raw_body}")
  3. Compare the result with v1 using a constant-time comparison
  4. Optionally reject requests where t is older than 5 minutes

RBL Events

Webhook events triggered during RBL monitoring checks.

Host Check Started Webhook

Triggered at the start of a check, when one of your hosts is checked.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

check_sid
required
string^PP[0-9a-f]{64}$

The unique SID of the check request.

required
object

A standard Host object.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "rbl.host.check.started",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
  • "host": {
    }
}

Host Check Completed Webhook

Triggered at the end of a check, when one of your hosts is checked. This event is trigger whether or not the host is listed.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

check_sid
required
string^PP[0-9a-f]{64}$

The unique SID of the check request.

required
object

A standard Host object.

listed
required
boolean

If the Host is listed or not.

total
required
integer
Default: 0

The total number of data sources this Host is currently listed on.

required
Array of objects (webhook_rbl_details)

An array of data sources that matched this Host. This can be empty if there were no matches.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "rbl.host.check.completed",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
  • "host": {
    },
  • "listed": true,
  • "total": 1,
  • "details": [
    ]
}

Host Listed Webhook

Triggered at the end of a check, when one of your hosts is listed. This event is only triggered in the event the host is listed.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

check_sid
required
string^PP[0-9a-f]{64}$

The unique SID of the check request.

required
object

A standard Host object.

listed
required
boolean

If the Host is listed or not. This will always be true for this event.

total
required
integer
Default: 0

The total number of data sources this Host is currently listed on.

required
Array of objects (webhook_rbl_details)

An array of data sources that matched this Host. This can be empty if there were no matches.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "rbl.host.listed",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
  • "host": {
    },
  • "listed": true,
  • "total": 1,
  • "details": [
    ]
}

Host De-Listed Webhook

Triggered at the end of a check, when one of your hosts is de-listed. This event will only trigger in the event the host is de-listed.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

check_sid
required
string^PP[0-9a-f]{64}$

The unique SID of the check request.

required
object

A standard Host object.

listed
required
boolean

If the Host is listed or not. This will always be false for this event.

total
required
integer
Default: 0

The total number of data sources this Host is currently listed on. This will always be 0 for this event.

details
required
Array of arrays

An array of data sources that matched this Host. This will always be empty for this event.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "rbl.host.delisted",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
  • "host": {
    },
  • "listed": false,
  • "total": 0,
  • "details": [ ]
}

Billing Events

Webhook events triggered related to accounts, billing, and payments.

Balance Alert Webhook

Triggered when your account balance goes below your configured alert threshold.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

balance
required
string

Your current account balance (in USD).

alert_threshold
required
string

Your configured low-balance alert threshold (in USD).

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "billing.balance.alert",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "balance": "12.34",
  • "alert_threshold": "15.00"
}

Recharge Success Webhook

Triggered when an auto-recharge is successful.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

falls_below
required
string

The currently configured auto-recharge threshold (in USD).

recharge_to
required
string

The currently configured auto-recharge amount (in USD).

required
object

Payment details related to this auto-recharge event.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "billing.recharge.success",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "falls_below": "5.00",
  • "recharge_to": "25.00",
  • "payment": {
    }
}

Recharge Failure Webhook

Triggered when an auto-recharge attempt fails.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

falls_below
required
string

The currently configured auto-recharge threshold (in USD).

recharge_to
required
string

The currently configured auto-recharge amount (in USD).

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "billing.recharge.failed",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "falls_below": "5.00",
  • "recharge_to": "25.00"
}

Renewal Success Webhook

Triggered when your billing package is set to auto-renew, and the auto-renewal process completes successfully.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The plan object that was just renewed.

required
object

Payment details related to this plan auto-renewal event.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "billing.renewal.success",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "plan": {
    },
  • "payment": {
    }
}

Renewal Failure Webhook

Triggered when your billing package is set to auto-renew, but the auto-renewal process attempt fails.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The plan object of the auto-renewal attempt.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "billing.renewal.failed",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "plan": {
    }
}

Card Expiration Webhook

Triggered when one of your credit cards is about to expire.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The payment source object that is expiring.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "expiring.card.alert",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "payment_source": {
    }
}

Plan Expiration Webhook

Triggered when your billing package is set to expire and auto-renewal is disabled.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The plan object that is expiring.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "expiring.plan.alert",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "plan": {
    }
}

Certificate Events

Webhook events triggered during certificate monitoring checks.

Expiration Trigger Webhook

Triggered when a certificate expiration threshold is crossed. This fires each time a new threshold bracket is entered (e.g., 60, 30, 15, 5, or 0 days remaining).

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

expiry_days
required
integer

Days until the certificate expires. Negative values indicate the certificate has already expired.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.expiration.trigger",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "expiry_days": 14
}

Expiration Resolve Webhook

Triggered when an expiring certificate is renewed. This occurs when the expiration threshold was crossed and the certificate has changed, indicating a renewal.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

expiry_days
required
integer

Days until the renewed certificate expires.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.expiration.resolve",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "expiry_days": 90
}

Error Trigger Webhook

Triggered when new certificate errors are detected during a check. The errors array contains only the newly detected errors, while current_errors contains all currently active errors.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

required
Array of objects (webhook_cert_error)

The newly detected certificate errors that triggered this event.

required
Array of objects (webhook_cert_error)

All currently active certificate errors for this monitor.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.error.trigger",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "errors": [
    ],
  • "current_errors": [
    ]
}

Error Resolve Webhook

Triggered when previously detected certificate errors are resolved. The resolved_errors array contains the errors that were resolved, while current_errors contains any remaining active errors.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

required
Array of objects (webhook_cert_error)

The certificate errors that have been resolved.

required
Array of objects (webhook_cert_error)

All currently active certificate errors for this monitor. This will be empty if all errors have been resolved.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.error.resolve",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "resolved_errors": [
    ],
  • "current_errors": [
    ]
}

Certificate Changed Webhook

Triggered when a certificate changes without a renewal. This indicates the certificate was replaced (e.g., different issuer or key) but was not previously in an expiration warning state.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The certificate monitor that triggered this event.

previous_fingerprint
required
string

The SHA-256 fingerprint of the previous certificate.

new_fingerprint
required
string

The SHA-256 fingerprint of the new certificate.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "cert.changed",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "monitor": {},
  • "previous_fingerprint": "SHA256:2b:4d:8e:6a:1c:3f:9d:7e:5a:0b:8c:2d:4f:6e:1a:3b:9c:7d:5e:0a:8b:2c:4d:6f:1e:3a:9b:7c:5d:0e:8a:2b",
  • "new_fingerprint": "SHA256:9f:3a:7c:1e:5b:8d:2f:6a:4c:0e:9b:3d:7f:1a:5c:8e:2b:6d:4f:0a:9c:3e:7b:1d:5f:8a:2c:6e:4b:0d:9a:3f"
}

Agent Events

Webhook events triggered for monitoring agent timeout and recovery.

Agent Timeout Webhook

Triggered when a persistent monitoring agent instance stops checking in beyond its configured timeout threshold. This event fires only when all persistent instances of the agent have timed out and there are newly timed-out instances to report.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The monitoring agent that triggered this event.

required
Array of objects (webhook_agent_instance)

The agent instances that have newly timed out. Only includes instances that have not been previously reported.

timeout_minutes
required
integer

The configured timeout threshold in minutes.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "agent.timeout",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "agent": {
    },
  • "instances": [
    ],
  • "timeout_minutes": 15
}

Agent Timeout Resolve Webhook

Triggered when a monitoring agent instance that had timed out resumes checking in. This event fires when at least one persistent instance recovers and the agent was previously in an alerted state.

header Parameters
X-Webhook-Signature
required
string
Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

HMAC-SHA256 signature for verifying webhook authenticity. Format: t={timestamp},v1={signature} where the signature is computed over {timestamp}.{raw_body} using the webhook's Signing Secret.

Request Body schema: application/json
event_sid
required
string^TA[0-9a-f]{32}$

The unique SID of the event.

event_type
required
string

The event type indicator.

event_date
required
string <date-time>

The date the event was triggered in GMT.

required
object

The monitoring agent that triggered this event.

required
Array of objects (webhook_agent_instance)

The agent instances that have recovered and resumed checking in.

timeout_minutes
required
integer

The configured timeout threshold in minutes.

Responses

Request samples

Content type
application/json
{
  • "event_sid": "TA67bca97cf42743beac24264790faf6dd",
  • "event_type": "agent.timeout.resolve",
  • "event_date": "2025-12-29T18:30:27+00:00",
  • "agent": {
    },
  • "instances": [
    ],
  • "timeout_minutes": 15
}