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.
/rbl/, /cert/, and /contact/ resource groupsDates and times in responses are in the time zone of the API application making the request, set on the application in the portal (Development > API Access > Applications). New applications use UTC; applications created before the setting existed use the time zone of the account owner. The MCP server uses the time zone of the API application it connects with.
API requests are subject to two levels of rate limiting:
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 windowRateLimit-Reset: seconds until the most restrictive window resetsWhen rate limited, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.
Repeated failed authentication from one address is limited as well: after 120 failures in a
minute, further requests from that address receive a 429 until the minute is over.
Every request that creates something (POST on a collection), a contact resend or
confirm, the certificate monitor DELETE, and the two check requests accept an
Idempotency-Key header: a unique value of your own (a UUID, for example), up to 255
printable characters. If the request is sent again with the same key within 24 hours, the
answer to the first request is returned, with the header Idempotent-Replayed: true, and
nothing is created, sent, billed or deleted a second time. The same key with a different
request is rejected with a 422. A request that was refused stores nothing, so a corrected
retry is judged afresh. Use it whenever a client retries after a timeout.
Every response carries an X-Request-Id header. Send your own (1 to 64 letters, digits,
-, _, . or :) and it is returned as sent; otherwise one is generated. Quote it when
you contact support about a request: it identifies the request in our logs.
Every GET response carries a weak ETag. Send it back in If-None-Match on the next
request for the same URL: when the answer has not changed you get 304 Not Modified with no
body, and your copy is still current. The tag changes whenever the body would.
Any GET accepts ?fields= with a comma-separated list of the keys to keep in each object
of data, for example ?fields=id,host,listed. A nested key is written with a dot
(listings.host). The rest of the response (total, page, ...) is unchanged. A field name
that no object has is rejected with a 422.
Responses are compressed with brotli or gzip when the request carries an Accept-Encoding
header that allows it. Most HTTP libraries send one by default.
All responses include a consistent JSON body with a status_code (which mirrors the HTTP
status) and a status_message:
{
"status_code": 404,
"status_message": "A description of the error."
}
Status Codes:
200 - Success400 - Bad request (malformed or invalid input, e.g. an invalid SID, or the SID of a
different kind of object)401 - Authentication failed403 - Forbidden (IP address restriction, or a feature not available on your plan)404 - Not found (the requested resource, or the endpoint itself, does not exist)405 - Method not allowed (an action that changes something was requested with GET)409 - Conflict (the resource is in a state that does not allow the action, or a request
with the same Idempotency-Key is still being processed)413 - The request body is larger than 1 MB422 - Validation failed (the input was understood but did not pass validation)429 - Rate limit exceeded, or a transient service condition (e.g. the service is
temporarily unavailable). In both cases the API sends a Retry-After header and the
RateLimit-* headers; clients should back off and retry rather than treat it as a hard
failure.500 - Server errorThe 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.
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.
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.
The Go SDK can be installed via go get:
go get github.com/generator-labs/go-sdk/v2
Or the source code can be downloaded directly from the GitHub repository.
The Go SDK requires Go >= 1.21.
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.
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.
A manual check is billed, so this request can be made safe to retry: send an
Idempotency-Key header with a unique value of your own (a UUID, for example). If the
request is sent again with the same key, the check that was already started is returned,
with the header Idempotent-Replayed: true, and no second check is started or billed. A
key is remembered for 24 hours, and belongs to one request: the same key with a different
host is rejected with a 422.
Rate limit: 10 requests/second
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value returns the check that was already started instead of starting another. |
| 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. |
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
{- "status_code": 200,
- "status_message": "Check started successfully.",
- "data": {
- "id": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
- "rbls": [ ]
}
}{- "event_sid": "TA9dbf5e2f7e924418a6d6b483a584adcf",
- "event_type": "rbl.host.check.completed",
- "event_date": "2025-12-22T23:43:52+00:00",
- "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
- "host": {
- "sid": "HT1b8ed8a3938fbeaedddd97eeaa3bf4ca",
- "name": "Production Mail Server",
- "host": "11.11.11.11"
}, - "listed": true,
- "total": 1,
- "details": [
- {
- "sid": "RB18c470cc518a09678bb280960dbdd524",
- "host": "spam.dnsbl.sorbs.net",
- "name": "SORBS Spam",
- "details": "Spam Received See: http://www.sorbs.net/lookup.shtml?10.10.10.10",
- "result": "listed",
- "pass_fail": false
}
]
}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
| id required | string^PP[0-9a-f]{64}$ Example: PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a Check id returned from /check/start. |
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| details | boolean Default: false A flag indicating if the RBL details should be returned with the response. |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/rbl/check/status/{id}.json?details=true \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Check status retrieved successfully.",
- "data": {
- "status": "completed",
- "checked_count": 75,
- "listed": 1,
- "listed_count": 2,
- "listed_details": [
- {
- "rbl": "RB18c470cc518a09678bb280960dbdd524",
- "details": "Spam Received See: http://www.sorbs.net/lookup.shtml?10.10.10.10",
- "listed": true,
- "result": "listed",
- "response_time": 22.34,
- "pass_fail": false
}
]
}
}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
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| page | integer >= 1 Default: 1 The current page number. |
| page_size | integer >= 1 Default: 100 Entries per page. |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/rbl/listings.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Listings",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 1,
- "total_listed": 1,
- "data": [
- {
- "id": "HT1a2b3c4d5e6f7890abcdef1234567890",
- "host": "mail.example.com",
- "name": "Production Mail Server",
- "type": "rbl",
- "parent": null,
- "status": "active",
- "profile": "RP9f8e7d6c5b4a3210fedcba0987654321",
- "contact_group": [
- "CG4f3e2d1c0b9a8776655443322110fedc"
], - "last_checked": "2024-01-20 14:22:00 EST",
- "first_listed": "2024-01-19 08:00:00 EST",
- "listed_period": "1 day 6 hours",
- "listed": true,
- "listed_count": 1,
- "listed_details": [
- {
- "rbl": "RB2d6b6be7c352d5e39756d004ee797388",
- "host": "zen.spamhaus.org",
- "details": null,
- "result": "listed",
- "pass_fail": false
}
], - "tags": [ ]
}
]
}Returns a full list of hosts configured on your account.
Rate limit: 100 requests/second
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| page | integer >= 1 Default: 1 The current page number. |
| page_size | integer >= 1 Default: 100 Entries per page. |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/rbl/hosts.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Hosts",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 2,
- "total_listed": 1,
- "data": [
- {
- "id": "HT1a2b3c4d5e6f7890abcdef1234567890",
- "host": "192.168.1.100",
- "name": "Production Mail Server",
- "type": "rbl",
- "parent": null,
- "status": "active",
- "profile": "RP9f8e7d6c5b4a3210fedcba0987654321",
- "contact_group": [
- "CG4f3e2d1c0b9a8776655443322110fedc"
], - "last_checked": "2024-01-20 14:22:00 EST",
- "first_listed": null,
- "listed_period": null,
- "listed": false,
- "listed_count": 0,
- "listed_details": [ ],
- "tags": [ ]
}, - {
- "id": "HTaa06c4fa7c23aa8a3a4e8d66922b0999",
- "host": "mail.example.com",
- "name": "Backup Mail Server",
- "type": "rbl",
- "parent": null,
- "status": "active",
- "profile": "RP9f8e7d6c5b4a3210fedcba0987654321",
- "contact_group": [
- "CG4f3e2d1c0b9a8776655443322110fedc"
], - "last_checked": "2024-01-16 09:15:00 EST",
- "first_listed": null,
- "listed_period": null,
- "listed": false,
- "listed_count": 0,
- "listed_details": [ ],
- "tags": [ ]
}
]
}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
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| 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. |
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'
{- "status_code": 200,
- "status_message": "Host added successfully.",
- "data": [
- {
- "id": "HTe092d4858135fad83dc938618a4ebfbf",
- "host": "10.10.10.10",
- "name": "Primary Mail Server",
- "parent": null
}
]
}Returns details for an individual host.
Rate limit: 100 requests/second
| id required | string^HT[0-9a-f]{32}$ Example: HT1a2b3c4d5e6f7890abcdef1234567890 Unique Host SID. |
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/rbl/hosts/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Hosts",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 1,
- "total_listed": 1,
- "data": [
- {
- "id": "HT1a2b3c4d5e6f7890abcdef1234567890",
- "host": "192.168.1.100",
- "name": "Production Mail Server",
- "type": "rbl",
- "parent": null,
- "status": "active",
- "profile": "RP9f8e7d6c5b4a3210fedcba0987654321",
- "contact_group": [
- "CG4f3e2d1c0b9a8776655443322110fedc"
], - "last_checked": "2024-01-20 14:22:00 EST",
- "first_listed": null,
- "listed_period": null,
- "listed": true,
- "listed_count": 1,
- "listed_details": [
- {
- "rbl": "RB2d6b6be7c352d5e39756d004ee797388",
- "host": "zen.spamhaus.org",
- "details": null,
- "result": "listed",
- "pass_fail": false
}
], - "tags": [ ]
}
]
}Updates an existing host on your account. A name that another of your hosts already has is rejected.
Rate limit: 50 requests/second
| id required | string^HT[0-9a-f]{32}$ Example: HT1a2b3c4d5e6f7890abcdef1234567890 Unique Host SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| 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. |
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'
{- "status_code": 200,
- "status_message": "Host updated successfully."
}Deletes an existing host on your account.
Rate limit: 50 requests/second
| id required | string^HT[0-9a-f]{32}$ Example: HT1a2b3c4d5e6f7890abcdef1234567890 Unique Host SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X DELETE https://api.generatorlabs.com/4.0/rbl/hosts/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Host deleted successfully."
}Pauses a Host, which temporarily stops all checks on this Host.
Rate limit: 50 requests/second
| id required | string^HT[0-9a-f]{32}$ Example: HT1a2b3c4d5e6f7890abcdef1234567890 Unique Host SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X POST https://api.generatorlabs.com/4.0/rbl/hosts/{id}/pause.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Host paused successfully."
}Re-activates a Host after it was paused. We will resume processing checks on this host.
Rate limit: 50 requests/second
| id required | string^HT[0-9a-f]{32}$ Example: HT1a2b3c4d5e6f7890abcdef1234567890 Unique Host SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X POST https://api.generatorlabs.com/4.0/rbl/hosts/{id}/resume.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Host activated successfully."
}Manage monitoring profiles that control which RBLs are checked for hosts.
Note: These features are only available to customers on a paid plan.
Returns a full list of monitoring profiles configured on your account.
Rate limit: 100 requests/second
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| page | integer >= 1 Default: 1 The current page number. |
| page_size | integer >= 1 Default: 100 Entries per page. |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/rbl/profiles.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Monitoring Profiles",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 1,
- "data": [
- {
- "id": "RP9f8e7d6c5b4a3210fedcba0987654321",
- "name": "My Custom Profile",
- "is_default": false,
- "run_time": "00:00",
- "frequency": "12_hours",
- "sync_method": "stay_in_sync",
- "total_entries": 2,
- "total_hosts": 10,
- "entries": [
- "RB1234567890abcdef1234567890abcdef",
- "RB0987654321fedcba0987654321fedcba"
]
}
]
}Create a new monitoring profile on your account.
Rate limit: 50 requests/second
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| 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. Required for Ultimate accounts; ignored on other tiers (which use the package's fixed interval). |
| sync_method | string Enum: "stay_in_sync" "use_my_selections" RBL sync method. Optional — automatically set to |
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'
{- "status_code": 200,
- "status_message": "Monitoring Profile added successfully.",
- "data": {
- "id": "RP9f8e7d6c5b4a3210fedcba0987654321"
}
}Returns details for an individual monitoring profile.
Rate limit: 100 requests/second
| id required | string^RP[0-9a-f]{32}$ Example: RP9f8e7d6c5b4a3210fedcba0987654321 Unique Profile SID. |
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/rbl/profiles/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Monitoring Profiles",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 1,
- "data": [
- {
- "id": "RP9f8e7d6c5b4a3210fedcba0987654321",
- "name": "My Custom Profile",
- "is_default": false,
- "run_time": "00:00",
- "frequency": "12_hours",
- "sync_method": "stay_in_sync",
- "total_entries": 2,
- "total_hosts": 10,
- "entries": [
- "RB1234567890abcdef1234567890abcdef",
- "RB0987654321fedcba0987654321fedcba"
]
}
]
}Updates an existing monitoring profile on your account.
Rate limit: 50 requests/second
| id required | string^RP[0-9a-f]{32}$ Example: RP9f8e7d6c5b4a3210fedcba0987654321 Unique Profile SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| name | string [ 1 .. 255 ] characters The label for this Profile. |
| entries | string Comma-separated list of RBL SIDs to include in this profile. Sending entries does not change the profile's |
| is_default | boolean Set this profile as the account default. An account always has a default profile: to change it, set |
| 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. |
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'
{- "status_code": 200,
- "status_message": "Monitoring Profile updated successfully."
}Deletes an existing monitoring profile on your account.
Rate limit: 50 requests/second
| id required | string^RP[0-9a-f]{32}$ Example: RP9f8e7d6c5b4a3210fedcba0987654321 Unique Profile SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X DELETE https://api.generatorlabs.com/4.0/rbl/profiles/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Monitoring profile deleted successfully."
}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.
Returns a full list of all active RBL sources on the system, including custom RBLs you've added.
Rate limit: 100 requests/second
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| page | integer >= 1 Default: 1 The current page number. |
| page_size | integer >= 1 Default: 100 Entries per page. |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/rbl/sources.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Data Sources",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 2,
- "data": [
- {
- "id": "RB1234567890abcdef1234567890abcdef",
- "name": "Spamhaus ZEN",
- "type": "rbl",
- "custom": false,
- "host": "zen.spamhaus.org",
}, - {
- "id": "RBabcdef1234567890abcdef1234567890",
- "name": "Microsoft SNDS Blocks",
- "type": "microsoft_snds",
- "custom": false,
- "host": "Microsoft SNDS Blocks",
}
]
}Create a new custom RBL source on your account.
Rate limit: 50 requests/second
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| 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. |
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'
{- "status_code": 200,
- "status_message": "Custom RBL added successfully.",
- "data": {
- "id": "RB1234567890abcdef1234567890abcdef"
}
}Returns details for an individual RBL source.
Rate limit: 100 requests/second
| id required | string^RB[0-9a-f]{32}$ Example: RB1234567890abcdef1234567890abcdef Unique RBL SID. |
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/rbl/sources/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Data Sources",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 1,
- "data": [
- {
- "id": "RB1234567890abcdef1234567890abcdef",
- "name": "Microsoft SNDS Blocks",
- "type": "microsoft_snds",
- "custom": false,
- "host": "Microsoft SNDS Blocks",
}
]
}Updates an existing RBL source on your account. Only the fields you send are changed:
custom_codes that are not sent are kept. A paused source can still be viewed, updated,
resumed and deleted, and is included in the list of sources.
Rate limit: 50 requests/second
| id required | string^RB[0-9a-f]{32}$ Example: RB1234567890abcdef1234567890abcdef Unique RBL SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| 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. |
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'
{- "status_code": 200,
- "status_message": "Custom RBL updated successfully."
}Deletes an existing RBL source on your account.
Rate limit: 50 requests/second
| id required | string^RB[0-9a-f]{32}$ Example: RB1234567890abcdef1234567890abcdef Unique RBL SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X DELETE https://api.generatorlabs.com/4.0/rbl/sources/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Custom RBL deleted successfully."
}Pauses an RBL source, temporarily excluding it from all checks.
Rate limit: 50 requests/second
| id required | string^RB[0-9a-f]{32}$ Example: RB1234567890abcdef1234567890abcdef Unique RBL SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X POST https://api.generatorlabs.com/4.0/rbl/sources/{id}/pause.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Custom RBL paused successfully."
}Resumes a paused RBL source, re-enabling it in all checks.
Rate limit: 50 requests/second
| id required | string^RB[0-9a-f]{32}$ Example: RB1234567890abcdef1234567890abcdef Unique RBL SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X POST https://api.generatorlabs.com/4.0/rbl/sources/{id}/resume.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Custom RBL activated successfully."
}Returns the active monitors that have a warning or an error their profile alerts on, each with those warnings and errors, worst first. Paused and archived monitors are left out.
A finding is listed only when it is a warning or an error and the monitor's profile alerts on it, the same rule as the alert emails. Each finding comes under one of the profile's alert settings:
| Findings | Profile setting |
|---|---|
Connection (CERT_NET*) |
alert_on_connection_failure |
Misconfigurations (CERT_CON01) |
alert_on_misconfigurations |
Certificate Flapping (CERT_CON02) |
alert_on_flapping |
Expiration (CERT_EXP*, including Expires Soon and Expired) |
alert_on_expiration |
Name check (CERT_HST*) |
alert_on_name_mismatch |
Chain of trust and revocation (CERT_TRU*, CERT_REV*) |
alert_on_ca_failure |
Integrity (CERT_SIG*, CERT_KEY*) |
Alert on integrity / configuration failures (portal) |
CAA (CERT_CAA*) |
alert_on_caa_failure |
Notices aren't listed, and a finding you've dismissed on a monitor (in the portal or with
POST /cert/findings/dismiss) is left out. To list every
current finding, notices and findings the profile doesn't alert on included, use
GET /cert/findings.
Besides the findings from the last check, this includes Expires Soon (CERT_EXP01) while the certificate the
last check read is inside its profile's warning period. When the last check read no certificate, Expires Soon
isn't listed, as no expiry alert is sent then; the connection failure is. It also includes
Certificate Flapping (CERT_CON02) when the certificate keeps changing between checks, and warnings such as
CAA Not Found (CERT_CAA01) whatever the expiry date.
The list is paged by monitor (page, page_size, up to 100 monitors a page), and total_errors counts the
warnings and errors on the page returned.
Rate limit: 100 requests/second
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| page | integer >= 1 Default: 1 The current page number. |
| page_size | integer >= 1 Default: 100 Entries per page. |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/cert/errors.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Certificate Errors",
- "total_errors": 3,
- "data": [
- {
- "id": "CM62944aeeee2b46d7a28221164f38976a",
- "hostname": "mail.example.com",
- "protocol": "https",
- "days_remaining": 5,
- "date_detected": "2024-01-20 14:22:00 UTC",
- "errors": [
- {
- "error_id": "CERT_HST02",
- "severity": "error",
- "error_type": "name_mismatch",
- "error_message": "Name Does Not Match"
}, - {
- "error_id": "CERT_EXP01",
- "severity": "warning",
- "error_type": "expiration",
- "error_message": "Expires Soon"
}
]
}, - {
- "id": "CMaa06c4fa7c23aa8a3a4e8d66922b0999",
- "hostname": "ldap.example.com",
- "protocol": "ldaps",
- "days_remaining": 30,
- "date_detected": "2024-01-19 10:15:00 UTC",
- "errors": [
- {
- "error_id": "CERT_TRU02",
- "severity": "error",
- "error_type": "ca_verification_failed",
- "error_message": "Not Trusted"
}
]
}
]
}Returns the number of warnings and errors the account's monitor profiles alert on, as plain text: the same
monitors and findings as GET /cert/errors (active monitors only,
warning or worse, only the findings the monitor's profile alerts on, dismissed findings left out), counted
across every page: the sum of total_errors over all of its pages.
Turning off an alert setting in a profile
takes those findings out of the count, so a monitoring plugin stops reporting them.
0 means nothing to report. It's meant for monitoring plugins, such as the Nagios and Zabbix plugins, which read
the body as a number.
A request that fails answers -1 in the body, with the error's status code.
Rate limit: 100 requests/second
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/cert/errors/count \ -u 'your_account_sid:your_auth_token'
3Returns the active monitors that have any current certificate finding, each with every one of its findings,
worst first: errors, warnings and notices, whatever the profile's
alert settings, as the portal's
Findings page shows them. Paused and archived
monitors are left out, and so is a finding you've dismissed on a monitor, in the portal or with
POST /cert/findings/dismiss, unless you set dismissed=1.
With dismissed=1, each active monitor also lists the findings dismissed from it, after its other findings,
with dismissed: true and alerts: false, and a monitor whose only findings are dismissed is listed too. Use it
to find what to restore with
POST /cert/findings/restore.
Each finding's alerts says whether the monitor's profile alerts on it, that is, whether it is listed by
GET /cert/errors and counted by
GET /cert/errors/count. Notices never alert. When the last
check read no certificate, Expires Soon (CERT_EXP01) is still listed, judged by the last certificate seen,
with alerts: false, as no expiry alert is sent without a certificate; the connection failure alerts instead.
Monitors are in name order. The list is paged by monitor (page, page_size, up to 100 monitors a page), and
total_findings counts the findings (not monitors) on the page returned, dismissed ones included when they're
listed.
Rate limit: 100 requests/second
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| page | integer >= 1 Default: 1 The current page number. |
| page_size | integer >= 1 Default: 100 Entries per page. |
| dismissed | string Enum: "1" "true" Set to |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/cert/findings.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Certificate Findings",
- "total_findings": 4,
- "data": [
- {
- "id": "CMaa06c4fa7c23aa8a3a4e8d66922b0999",
- "hostname": "ldap.example.com",
- "protocol": "ldaps",
- "days_remaining": 30,
- "date_detected": "2024-01-19 10:15:00 UTC",
- "findings": [
- {
- "finding_id": "CERT_TRU02",
- "severity": "error",
- "finding_type": "ca_verification_failed",
- "message": "Not Trusted",
- "alerts": true,
- "dismissible": false,
- "dismissed": false
}
]
}, - {
- "id": "CM62944aeeee2b46d7a28221164f38976a",
- "hostname": "mail.example.com",
- "protocol": "https",
- "days_remaining": 5,
- "date_detected": "2024-01-20 14:22:00 UTC",
- "findings": [
- {
- "finding_id": "CERT_HST02",
- "severity": "error",
- "finding_type": "name_mismatch",
- "message": "Name Does Not Match",
- "alerts": true,
- "dismissible": false,
- "dismissed": false
}, - {
- "finding_id": "CERT_EXP01",
- "severity": "warning",
- "finding_type": "expiration",
- "message": "Expires Soon",
- "alerts": true,
- "dismissible": false,
- "dismissed": false
}, - {
- "finding_id": "CERT_CAA01",
- "severity": "warning",
- "finding_type": "caa_record_invalid",
- "message": "CAA Not Found",
- "alerts": false,
- "dismissible": true,
- "dismissed": false
}
]
}
]
}Dismisses one or more findings on the account's monitors, the same as dismissing them in the portal, for findings you've decided not to act on.
Leave monitors out to dismiss the findings from every active monitor that has them now. When you name
monitors, the findings are dismissed from each of them, whatever its status, whether or not it has them now, so
they stay dismissed if they appear later.
Only these findings can be dismissed, the same as in the portal:
| Key | Label |
|---|---|
CERT_CAA01 |
CAA Not Found |
CERT_CAA02 |
CAA Not Specific |
CERT_LIF01 |
Long Reg Period |
CERT_HST01 |
Matched CN, No SAN |
CERT_TRU03 |
Root Sent |
A dismissed finding is left out of the monitor's findings,
GET /cert/findings,
GET /cert/errors,
GET /cert/errors/count and the alerts, until it's restored with
POST /cert/findings/restore.
Each finding's dismissible in GET /cert/findings says whether it can be dismissed.
data lists the monitors that changed, in hostname order, each with the finding keys changed on it, and total
counts them.
This request must be a POST; a GET or HEAD is answered with a 405.
Rate limit: 100 requests/second
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| finding_id required | string The finding key to dismiss, or several separated by commas. |
| monitors | string Certificate Monitor SIDs separated by commas. Leave it out to dismiss from every active monitor that has the finding now. |
curl -X POST https://api.generatorlabs.com/4.0/cert/findings/dismiss.json \ -u 'your_account_sid:your_auth_token' \ -d finding_id='CERT_CAA01'
{- "status_code": 200,
- "status_message": "Certificate Findings dismissed successfully.",
- "total": 2,
- "data": [
- {
- "id": "CMaa06c4fa7c23aa8a3a4e8d66922b0999",
- "hostname": "ldap.example.com",
- "finding_ids": [
- "CERT_CAA01",
- "CERT_CAA02"
]
}, - {
- "id": "CM62944aeeee2b46d7a28221164f38976a",
- "hostname": "mail.example.com",
- "finding_ids": [
- "CERT_CAA01"
]
}
]
}Restores one or more dismissed findings on the account's monitors, the same as Restore in the portal.
Leave monitors out to restore the findings on every monitor they're dismissed from, or name the monitors to
restore them on.
Only these findings can be dismissed and restored, the same as in the portal:
| Key | Label |
|---|---|
CERT_CAA01 |
CAA Not Found |
CERT_CAA02 |
CAA Not Specific |
CERT_LIF01 |
Long Reg Period |
CERT_HST01 |
Matched CN, No SAN |
CERT_TRU03 |
Root Sent |
A restored finding is back in the monitor's findings,
GET /cert/findings,
GET /cert/errors,
GET /cert/errors/count and the alerts, by the same rules as any
other finding.
data lists the monitors that changed, in hostname order, each with the finding keys changed on it, and total
counts them.
This request must be a POST; a GET or HEAD is answered with a 405.
Rate limit: 100 requests/second
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| finding_id required | string The finding key to restore, or several separated by commas. |
| monitors | string Certificate Monitor SIDs separated by commas. Leave it out to restore on every monitor the finding is dismissed from. |
curl -X POST https://api.generatorlabs.com/4.0/cert/findings/restore.json \ -u 'your_account_sid:your_auth_token' \ -d finding_id='CERT_CAA01'
{- "status_code": 200,
- "status_message": "Certificate Findings restored successfully.",
- "total": 2,
- "data": [
- {
- "id": "CMaa06c4fa7c23aa8a3a4e8d66922b0999",
- "hostname": "ldap.example.com",
- "finding_ids": [
- "CERT_CAA01",
- "CERT_CAA02"
]
}, - {
- "id": "CM62944aeeee2b46d7a28221164f38976a",
- "hostname": "mail.example.com",
- "finding_ids": [
- "CERT_CAA01"
]
}
]
}Returns a full list of certificate monitors configured on your account. Archived monitors are left out; pass
status=archived to list only the archived ones.
Rate limit: 100 requests/second
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| page | integer >= 1 Default: 1 The current page number. |
| page_size | integer >= 1 Default: 100 Entries per page. |
| status | string Value: "archived" Set to |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/cert/monitors.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Certificate Monitors",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 2,
- "data": [
- {
- "id": "CM62944aeeee2b46d7a28221164f38976a",
- "name": "Production Web Server",
- "hostname": "example.com",
- "protocol": "https",
- "port": 443,
- "status": "active",
- "days_remaining": 45,
- "profile": "CP15d4e891d784977cacbfcbb00c48f133",
- "contact_group": [
- "CG4f3e2d1c0b9a8776655443322110fedc"
], - "tags": [ ],
- "last_checked": "2024-01-20 14:22:00 UTC"
}, - {
- "id": "CMaa06c4fa7c23aa8a3a4e8d66922b0999",
- "name": "Mail Server Certificate",
- "hostname": "mail.example.com",
- "protocol": "smtps",
- "port": 465,
- "status": "active",
- "days_remaining": 90,
- "profile": "CP15d4e891d784977cacbfcbb00c48f133",
- "contact_group": [
- "CG4f3e2d1c0b9a8776655443322110fedc"
], - "tags": [ ],
- "last_checked": "2024-01-16 09:15:00 UTC"
}
]
}Create a new certificate monitor on your account. Only hostname, protocol and name are required: without a
profile the monitor uses the account's default profile, and without contact groups the account's default
contact group.
The hostname is checked the same way as in the portal. It can't carry a protocol prefix other than the protocol's
own (https:// for https, which is removed), and a custom port goes on the hostname (mail.example.com:2500,
[2001:db8::1]:8443). On a profile checked from our system, a name also has to include its domain, resolve, and
resolve only to public addresses; a profile checked by a monitoring agent skips the lookup. A failed check, a name
already used by another monitor that isn't archived, the same hostname and protocol as another monitor that isn't
archived, or an account at its monitor limit, is rejected with a 422.
Rate limit: 50 requests/second
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| hostname required | string The hostname or IP address to monitor, with an optional |
| 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 .. 256 ] characters Label for the Certificate Monitor. Must be unique among the account's monitors that aren't archived. |
| profile | string^CP[0-9a-f]{32}$ Certificate Monitoring Profile id to use on this monitor. Defaults to the account's default profile. |
| contact_group | string One Contact Group id to send this monitor's alerts to. Use |
| contact_groups | string Comma-separated list of Contact Group ids to send this monitor's alerts to. Used instead of |
| tags | string Comma-separated list of tags for organization. |
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'
{- "status_code": 200,
- "status_message": "Certificate Monitor added successfully.",
- "data": {
- "id": "CM62944aeeee2b46d7a28221164f38976a"
}
}Returns details for an individual certificate monitor.
Rate limit: 100 requests/second
| id required | string^CM[0-9a-f]{32}$ Example: CM62944aeeee2b46d7a28221164f38976a Unique Certificate Monitor SID. |
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/cert/monitors/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Certificate Monitors",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 1,
- "data": [
- {
- "id": "CM62944aeeee2b46d7a28221164f38976a",
- "name": "Production Web Server",
- "hostname": "example.com",
- "protocol": "https",
- "port": 443,
- "status": "active",
- "days_remaining": 45,
- "profile": "CP15d4e891d784977cacbfcbb00c48f133",
- "contact_group": [
- "CG4f3e2d1c0b9a8776655443322110fedc"
], - "tags": [ ],
- "last_checked": "2024-01-20 14:22:00 UTC"
}
]
}Updates an existing certificate monitor on your account. Only the fields you send are
changed; when contact_group or contact_groups is sent, it replaces the monitor's contact groups.
A monitor's hostname and protocol can't be changed: add a new monitor instead. Moving a monitor from a
profile checked by a monitoring agent to one checked from our system checks its hostname the same way
as adding it there, and a name already used by another monitor that isn't archived is rejected with a 422.
Rate limit: 50 requests/second
| id required | string^CM[0-9a-f]{32}$ Example: CM62944aeeee2b46d7a28221164f38976a Unique Certificate Monitor SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| name | string [ 1 .. 256 ] 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 One Contact Group SID to use for this monitor. Use |
| contact_groups | string Comma-separated list of one or more Contact Group SIDs to use for this monitor. Used instead of |
| tags | string Comma-separated list of tags for organization. |
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'
{- "status_code": 200,
- "status_message": "Certificate Monitor updated successfully."
}Archives or deletes a certificate monitor on your account. The first delete archives the monitor: it's no longer
checked or billed, it's left out of the monitor list (unless you ask for status=archived), and its reports and
history are kept. Resume it to make it active again. Deleting an archived monitor removes it for good.
Rate limit: 50 requests/second
| id required | string^CM[0-9a-f]{32}$ Example: CM62944aeeee2b46d7a28221164f38976a Unique Certificate Monitor SID. |
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X DELETE https://api.generatorlabs.com/4.0/cert/monitors/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Certificate Monitor archived successfully. Delete it again to remove it permanently."
}Pauses a certificate monitor on your account: it's no longer checked or billed. Pausing an archived monitor
brings it back from the archive as a paused monitor, so it counts toward the account's monitor limit again;
an account at its limit is rejected with a 422.
Rate limit: 50 requests/second
| id required | string^CM[0-9a-f]{32}$ Example: CM4f3e2d1c0b9a8776655443322110fedc Unique Certificate Monitor SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X POST https://api.generatorlabs.com/4.0/cert/monitors/{id}/pause.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Certificate Monitor paused successfully."
}Resumes a paused or archived certificate monitor on your account. A resumed archived monitor counts toward the
account's monitor limit again; an account at its limit is rejected with a 422.
Rate limit: 50 requests/second
| id required | string^CM[0-9a-f]{32}$ Example: CM4f3e2d1c0b9a8776655443322110fedc Unique Certificate Monitor SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X POST https://api.generatorlabs.com/4.0/cert/monitors/{id}/resume.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Certificate Monitor activated successfully."
}Requests a check of a certificate monitor now, for example right after a certificate was renewed.
This process is asynchronous: the check is queued and the request returns right away. The result shows up on the
monitor (last_checked, status, days_remaining) and in the certificate errors a few seconds later.
There is no charge beyond the monitor's normal daily charge. A check on request also runs while the account's scheduled checks are paused.
A monitor can be checked on request at most once a minute, and 10 times in any 24 hours; an account can request
100 checks in any 24 hours. Requests over a limit are rejected with a 429 and a Retry-After header.
A paused or archived monitor, an account on hold, and a monitor whose profile is checked by monitoring agents
with none assigned are rejected with a 422.
This request can be made safe to retry: send an Idempotency-Key header with a unique value of your own (a UUID,
for example). If the request is sent again with the same key, the first answer is returned, with the header
Idempotent-Replayed: true, and no second check is queued; its status is the queued check's current status,
completed once the check has run, otherwise queued. A key is remembered for 24 hours, and belongs to one
request: the same key for a different monitor is rejected with a 422. Without a key, a repeat while the first
request is still waiting returns that request.
Rate limit: 5 requests/second
| id required | string^CM[0-9a-f]{32}$ Example: CM4f3e2d1c0b9a8776655443322110fedc Unique Certificate Monitor SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value returns the first answer instead of queuing another check. |
curl -X POST https://api.generatorlabs.com/4.0/cert/monitors/{id}/check.json \ -u 'your_account_sid:your_auth_token' \ -H 'Idempotency-Key: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55'
{- "status_code": 200,
- "status_message": "Certificate Monitor check queued successfully.",
- "data": {
- "id": "TAde34e777d435460eac2e8458250849d7",
- "monitor": "CM4f3e2d1c0b9a8776655443322110fedc",
- "status": "queued",
- "last_checked": "2026-10-05 13:46:25 EDT"
}
}Manage certificate monitoring profiles that control validation rules and alert thresholds.
Returns a full list of certificate monitoring profiles configured on your account.
Rate limit: 100 requests/second
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| page | integer >= 1 Default: 1 The current page number. |
| page_size | integer >= 1 Default: 100 Entries per page. |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/cert/profiles.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Certificate Profiles",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 2,
- "data": [
- {
- "id": "CP79b597e61a984a35b5eb7dcdbc3de53c",
- "name": "Standard SSL Profile",
- "is_default": false,
- "expiration_thresholds": [
- 30,
- 14,
- 7
], - "alert_on_expiration": true,
- "alert_on_name_mismatch": true,
- "alert_on_ca_failure": true,
- "alert_on_connection_failure": true,
- "alert_on_caa_failure": false,
- "alert_on_misconfigurations": true,
- "alert_on_changes": true,
- "private_cas": [ ],
- "monitoring_agents": [ ],
- "monitor_count": 5
}, - {
- "id": "CP3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a",
- "name": "Critical Services Profile",
- "is_default": false,
- "expiration_thresholds": [
- 60,
- 30,
- 14,
- 7,
- 3
], - "alert_on_expiration": true,
- "alert_on_name_mismatch": true,
- "alert_on_ca_failure": true,
- "alert_on_connection_failure": true,
- "alert_on_caa_failure": true,
- "alert_on_misconfigurations": true,
- "alert_on_changes": true,
- "private_cas": [ ],
- "monitoring_agents": [ ],
- "monitor_count": 2
}
]
}Create a new certificate monitoring profile on your account. An alert_on_* field you leave out gets
its default below. The alert fields take true, 1, on or yes to switch an alert on; any other
value, including false and 0, switches it off.
Rate limit: 50 requests/second
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| name required | string [ 1 .. 256 ] characters Label for the Certificate Profile. |
| expiration_thresholds required | string Comma-separated list of days before expiration to send alerts (e.g., '30,14,7'): 1 to 10 values, each a whole number from 0 to 90. Anything else, including empty entries ('30,14,') and decimals, is rejected with a 422. |
| 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. |
| fingerprint_enabled | boolean Default: true After the certificate check, send a few standard protocol commands (EHLO / HELP, CAPABILITY, FEAT, a GET of a page that doesn't exist and of the home page, ...) to identify the server software and version. These are visible in your server logs. |
| is_default | boolean Set this profile as the account default ( |
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
{- "status_code": 200,
- "status_message": "Certificate Profile added successfully.",
- "data": {
- "id": "CP79b597e61a984a35b5eb7dcdbc3de53c"
}
}Returns details for an individual certificate monitoring profile.
Rate limit: 100 requests/second
| id required | string^CP[0-9a-f]{32}$ Example: CP79b597e61a984a35b5eb7dcdbc3de53c Unique Certificate Profile SID. |
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/cert/profiles/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Certificate Profiles",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 1,
- "data": [
- {
- "id": "CP79b597e61a984a35b5eb7dcdbc3de53c",
- "name": "Standard SSL Profile",
- "is_default": false,
- "expiration_thresholds": [
- 30,
- 14,
- 7
], - "alert_on_expiration": true,
- "alert_on_name_mismatch": true,
- "alert_on_ca_failure": true,
- "alert_on_connection_failure": true,
- "alert_on_caa_failure": false,
- "alert_on_misconfigurations": true,
- "alert_on_changes": true,
- "private_cas": [ ],
- "monitoring_agents": [ ],
- "monitor_count": 5
}
]
}Updates an existing certificate monitoring profile on your account. Only the fields you
send are changed, including each alert_on_* field: true, 1, on or yes switches that alert on,
any other value (including false and 0) switches it off, and a field you leave out stays as it is. An account always has a default profile: to change it, set is_default
to true on another profile; setting it to false on the default profile is rejected.
Rate limit: 50 requests/second
| id required | string^CP[0-9a-f]{32}$ Example: CP79b597e61a984a35b5eb7dcdbc3de53c Unique Certificate Profile SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| name | string [ 1 .. 256 ] 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'): 1 to 10 values, each a whole number from 0 to 90. Anything else, including empty entries ('30,14,') and decimals, is rejected with a 422. |
| 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. |
| fingerprint_enabled | boolean After the certificate check, send a few standard protocol commands (EHLO / HELP, CAPABILITY, FEAT, a GET of a page that doesn't exist and of the home page, ...) to identify the server software and version. These are visible in your server logs. |
| is_default | boolean Set this profile as the account default ( |
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
{- "status_code": 200,
- "status_message": "Certificate Profile updated successfully."
}Deletes an existing certificate monitoring profile on your account.
Rate limit: 50 requests/second
| id required | string^CP[0-9a-f]{32}$ Example: CP79b597e61a984a35b5eb7dcdbc3de53c Unique Certificate Profile SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X DELETE https://api.generatorlabs.com/4.0/cert/profiles/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Certificate Profile deleted successfully."
}Returns a full list of contacts on your account.
Rate limit: 100 requests/second
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| page | integer >= 1 Default: 1 The current page number. |
| page_size | integer >= 1 Default: 100 Entries per page. |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/contact/contacts.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Contacts",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 2,
- "data": [
- {
- "id": "COabcdef1234567890abcdef1234567890",
- "type": "email",
- "status": "active",
- "schedule": "every_check",
- "contact": "admin@example.com",
- "contact_group": [
- "CG4f3e2d1c0b9a8776655443322110fedc"
]
}
]
}Create a new contact on your account.
Rate limit: 50 requests/second
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| 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. Write-only: it is never returned in responses. |
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'
{- "status_code": 200,
- "status_message": "Contact added successfully.",
- "data": {
- "id": "COabcdef1234567890abcdef1234567890",
- "contact": "admin@example.com"
}
}Returns the details for a single contact.
Rate limit: 100 requests/second
| id required | string^CO[0-9a-f]{32}$ Example: COabcdef1234567890abcdef1234567890 The unique SID of the Contact. |
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/contact/contacts/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Contacts",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 1,
- "data": [
- {
- "id": "COabcdef1234567890abcdef1234567890",
- "type": "email",
- "status": "active",
- "schedule": "every_check",
- "contact": "admin@example.com",
- "contact_group": [
- "CG4f3e2d1c0b9a8776655443322110fedc"
]
}
]
}Updates an existing contact on your account.
A contact's value (the address, number or URL its alerts are sent to) can not be changed:
it was confirmed by whoever receives the alerts. To change it, delete the contact and add a
new one. Only the fields you send are changed; a contact whose contact_group is not sent
keeps its groups.
Rate limit: 50 requests/second
| id required | string^CO[0-9a-f]{32}$ Example: COabcdef1234567890abcdef1234567890 Unique Contact SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| 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" |
curl -X PUT https://api.generatorlabs.com/4.0/contact/contacts/{id}.json \ -u 'your_account_sid:your_auth_token' \ -d contact_group='CG4f3e2d1c0b9a8776655443322110fedc,CG5a6b7c8d9e0f1234567890abcdef1234'
{- "status_code": 200,
- "status_message": "Contact updated successfully."
}Deletes an existing contact on your account.
Rate limit: 50 requests/second
| id required | string^CO[0-9a-f]{32}$ Example: COabcdef1234567890abcdef1234567890 Unique Contact SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X DELETE https://api.generatorlabs.com/4.0/contact/contacts/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Contact deleted successfully."
}Pause a contact. This will temporarily stop notifications to this contact.
Rate limit: 50 requests/second
| id required | string^CO[0-9a-f]{32}$ Example: COd3dca251d33135e0a518d7c49b89dc61 The unique SID of the Contact. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/pause.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Contact paused successfully."
}Re-activate a contact after it was paused. We will resume sending notifications to this contact.
Rate limit: 50 requests/second
| id required | string^CO[0-9a-f]{32}$ Example: COd3dca251d33135e0a518d7c49b89dc61 The unique SID of the Contact. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/resume.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Contact activated successfully."
}Resends the authorization confirmation to the specified contact. The contact must be in 'pending' status.
| id required | string^CO[0-9a-f]{32}$ Example: COd3dca251d33135e0a518d7c49b89dc61 The unique SID of the Contact. |
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/resend.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Contact authorization re-sent successfully."
}Confirms a pending contact using a confirmation code.
Rate limit: 50 requests/second
| id required | string^CO[0-9a-f]{32}$ Example: COabcdef1234567890abcdef1234567890 The unique SID of the Contact. |
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| authcode required | string Confirmation token delivered to the Contact. |
curl -X POST https://api.generatorlabs.com/4.0/contact/contacts/{id}/confirm.json \ -d authcode='3Kx3se' \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Contact authorized successfully."
}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
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| page | integer >= 1 Default: 1 The current page number. |
| page_size | integer >= 1 Default: 100 Entries per page. |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/contact/groups.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Contact Groups",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 1,
- "data": [
- {
- "id": "CG4f3e2d1c0b9a8776655443322110fedc",
- "name": "Primary Contacts",
- "is_default": true,
- "total_members": 3,
- "total_hosts": 10
}
]
}Create a new contact group on your account.
Rate limit: 50 requests/second
| Idempotency-Key | string <= 255 characters Example: 1f0d2c4e-7a5b-4d1c-9c1e-2b7a6e0f3d55 A unique value for this request (up to 255 printable characters). A repeat with the same value within 24 hours returns the first answer with |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| name required | string [ 1 .. 255 ] characters Name for the contact group. |
| is_default | boolean Set this Contact Group as the default. |
curl -X POST https://api.generatorlabs.com/4.0/contact/groups.json \ -u 'your_account_sid:your_auth_token' \ -d name='Primary Contacts'
{- "status_code": 200,
- "status_message": "Contact group added successfully.",
- "data": {
- "id": "CG4f3e2d1c0b9a8776655443322110fedc"
}
}Return details for a single Contact Group, based on the SID passed.
Rate limit: 100 requests/second
| id required | string^CG[0-9a-f]{32}$ Example: CG4f3e2d1c0b9a8776655443322110fedc The unique SID of the Contact Group. |
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -G https://api.generatorlabs.com/4.0/contact/groups/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Contact Groups",
- "page": 1,
- "page_size": 100,
- "total_pages": 1,
- "total": 1,
- "data": [
- {
- "id": "CG4f3e2d1c0b9a8776655443322110fedc",
- "name": "Primary Contacts",
- "is_default": true,
- "total_members": 3,
- "total_hosts": 10
}
]
}Updates an existing contact group on your account.
Rate limit: 50 requests/second
| id required | string^CG[0-9a-f]{32}$ Example: CG4f3e2d1c0b9a8776655443322110fedc Unique Contact Group SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
| name | string [ 1 .. 255 ] characters Name for the contact group. |
| is_default | boolean Set this Contact Group as the default. |
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'
{- "status_code": 200,
- "status_message": "Contact group updated successfully."
}Deletes an existing contact group on your account.
Rate limit: 50 requests/second
| id required | string^CG[0-9a-f]{32}$ Example: CG4f3e2d1c0b9a8776655443322110fedc Unique Contact Group SID. |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X DELETE https://api.generatorlabs.com/4.0/contact/groups/{id}.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Contact Group deleted successfully."
}Returns your account: its balance, whether its scheduled checks are running, and how much of what your plan allows is in use.
Rate limit: 100 requests/second
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl https://api.generatorlabs.com/4.0/account.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Account retrieved successfully.",
- "data": {
- "id": "ACb7f12cedb02b1decf002747d81cba331",
- "company_name": "Example Hosting",
- "owner": "admin@example.com",
- "timezone": "America/Toronto",
- "balance": 80.1226,
- "checks_enabled": true,
- "on_hold": false,
- "rbl": {
- "active_hosts": 25,
- "listed_hosts": 0,
- "hosts_allowed": "unlimited",
- "plan": {
- "rate_id": 40,
- "title": "Ultimate Plan",
- "short_name": "Ultimate Plan",
- "monthly_cost": 0,
- "duration_months": 0,
- "hosts_allowed": "unlimited",
- "check_frequency_minutes": 720,
- "manual_checks_per_day": 20,
- "custom_sources_allowed": true,
- "premium_sources_allowed": true,
- "billing_model": "pay-per-check"
}
}, - "cert": {
- "monitors": 30,
- "active_monitors": 30,
- "monitors_allowed": 5000
}, - "contact": {
- "contacts": 10,
- "contacts_allowed": 100
}
}
}Returns your account balance as a plain number with four decimals, followed by a newline, for use in monitoring
plugins and scripts. The body is -1 when the balance can't be read.
Rate limit: 100 requests/second
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl https://api.generatorlabs.com/4.0/account/balance \ -u 'your_account_sid:your_auth_token'
80.1226
Stops the scheduled checks of every host and certificate monitor on your account. A check that is requested by hand (a manual RBL check, or a certificate monitor check on request) still runs while they are paused.
Rate limit: 10 requests/second
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X POST https://api.generatorlabs.com/4.0/account/checks/pause.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Account checks paused successfully."
}Restarts the scheduled checks of every host and certificate monitor on your account. Has no effect when they are already running.
Rate limit: 10 requests/second
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl -X POST https://api.generatorlabs.com/4.0/account/checks/resume.json \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Account checks resumed successfully."
}Returns what your account was charged, by month and service, newest first.
Rate limit: 50 requests/second
| fields | string Example: fields=id,host,listed Comma-separated list of the keys to keep in each object of |
| months | integer [ 1 .. 24 ] Default: 12 How many months to return, the current month included. |
| If-None-Match | string Example: W/"53b07f718e365c7743d1108cd2de9676" The |
| X-Request-Id | string <= 64 characters ^[A-Za-z0-9._:-]{1,64}$ Example: deploy-42-step-3 Your id for this request, returned as sent. One is generated when it is missing or not usable. |
curl https://api.generatorlabs.com/4.0/account/usage.json?months=3 \ -u 'your_account_sid:your_auth_token'
{- "status_code": 200,
- "status_message": "Account usage retrieved successfully.",
- "months": 3,
- "total": 2,
- "data": [
- {
- "month": "2026-10",
- "service": "RBL Monitoring",
- "type": "RBL Monitoring - Usage",
- "cost": 117.4272,
- "details": {
- "hosts": 24464
}
}, - {
- "month": "2026-10",
- "service": "Certificate Monitoring",
- "type": "Certificate Monitoring",
- "cost": 1.59,
- "details": {
- "count": 159
}
}
]
}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:
t and v1 from the X-Webhook-Signature headerHMAC-SHA256(signing_secret, "{t}.{raw_body}")v1 using a constant-time comparisont is older than 5 minutesTriggered at the start of a check, when one of your hosts is checked.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "rbl.host.check.started",
- "event_date": "2025-12-29T18:30:27+00:00",
- "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
- "host": {
- "sid": "HTd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "Primary Mail Server",
- "host": "10.10.10.10"
}
}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.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "rbl.host.check.completed",
- "event_date": "2025-12-29T18:30:27+00:00",
- "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
- "host": {
- "sid": "HTd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "Primary Mail Server",
- "host": "10.10.10.10"
}, - "listed": true,
- "total": 1,
- "details": [
- {
- "sid": "RBa357bc5d6d79095af5ad8578ec5c1584",
- "host": "Project Honey Pot",
- "name": "Project Honey Pot",
- "details": "Last Activity: 0 days, Threat Score: 29/255, Visitor Type: Search Engine - https://www.projecthoneypot.org/ip_1.1.1.1",
- "result": "listed",
- "pass_fail": false
}
]
}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.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "rbl.host.listed",
- "event_date": "2025-12-29T18:30:27+00:00",
- "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
- "host": {
- "sid": "HTd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "Primary Mail Server",
- "host": "10.10.10.10"
}, - "listed": true,
- "total": 1,
- "details": [
- {
- "sid": "RBa357bc5d6d79095af5ad8578ec5c1584",
- "host": "Project Honey Pot",
- "name": "Project Honey Pot",
- "details": "Last Activity: 0 days, Threat Score: 29/255, Visitor Type: Search Engine - https://www.projecthoneypot.org/ip_1.1.1.1",
- "result": "listed",
- "pass_fail": false
}
]
}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.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "rbl.host.delisted",
- "event_date": "2025-12-29T18:30:27+00:00",
- "check_sid": "PPf93d71a4a9892defde3ce995b141391dbbb95dcb000279fe51f4191f8bf41e1a",
- "host": {
- "sid": "HTd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "Primary Mail Server",
- "host": "10.10.10.10"
}, - "listed": false,
- "total": 0,
- "details": [ ]
}Triggered when your account balance goes below your configured alert threshold.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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). |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "billing.balance.alert",
- "event_date": "2025-12-29T18:30:27+00:00",
- "balance": "12.34",
- "alert_threshold": "15.00"
}Triggered when an auto-recharge is successful.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "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": {
- "sid": "PAa357bc5d6d79095af5ad8578ec5c1584",
- "amount": "25.00",
- "status": "Approved",
- "details": "Credit Card - (xxxx xxxx xxxx 0005) #3RgEZcGBRhmtuYiT0bJxifk1"
}
}Triggered when an auto-recharge attempt fails.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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). |
{- "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"
}Triggered when your billing package is set to auto-renew, and the auto-renewal process completes successfully.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "billing.renewal.success",
- "event_date": "2025-12-29T18:30:27+00:00",
- "plan": {
- "name": "Professional",
- "period": "6 Months",
- "expires": "2025-10-31",
- "auto_renew_enabled": true
}, - "payment": {
- "sid": "PAa357bc5d6d79095af5ad8578ec5c1584",
- "amount": "25.00",
- "status": "Approved",
- "details": "Credit Card - (xxxx xxxx xxxx 0005) #3RgEZcGBRhmtuYiT0bJxifk1"
}
}Triggered when your billing package is set to auto-renew, but the auto-renewal process attempt fails.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "billing.renewal.failed",
- "event_date": "2025-12-29T18:30:27+00:00",
- "plan": {
- "name": "Professional",
- "period": "6 Months",
- "expires": "2025-10-31",
- "auto_renew_enabled": true
}
}Triggered when one of your credit cards is about to expire.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "expiring.card.alert",
- "event_date": "2025-12-29T18:30:27+00:00",
- "payment_source": {
- "sid": "PSa357bc5d6d79095af5ad8578ec5c1584",
- "type": "American Express",
- "details": "xxxx xxxx xxxx 0005",
- "expires": "2025-10-31"
}
}Triggered when your billing package is set to expire and auto-renewal is disabled.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "expiring.plan.alert",
- "event_date": "2025-12-29T18:30:27+00:00",
- "plan": {
- "name": "Professional",
- "period": "6 Months",
- "expires": "2025-10-31",
- "auto_renew_enabled": false
}
}Triggered when a certificate reaches one of the expiration alert thresholds set on the monitor's profile, once for each threshold (for example at 30, 15 and 5 days before it expires).
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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 Whole days until the certificate expires. It doesn't go below 0: a certificate that has expired reports 0. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "cert.expiration.trigger",
- "event_date": "2025-12-29T18:30:27+00:00",
- "monitor": {
- "sid": "CMd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "example.com",
}, - "expiry_days": 14
}Triggered when an expiring certificate is renewed. This occurs when the expiration threshold was crossed and the certificate has changed, indicating a renewal.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "cert.expiration.resolve",
- "event_date": "2025-12-29T18:30:27+00:00",
- "monitor": {
- "sid": "CMd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "example.com",
}, - "expiry_days": 90
}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. Only the findings the monitor's profile alerts on are included, and a finding dismissed on the monitor is left out.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "cert.error.trigger",
- "event_date": "2025-12-29T18:30:27+00:00",
- "monitor": {
- "sid": "CMd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "example.com",
}, - "errors": [
- {
- "code": "50102",
- "id": "CERT_NET04",
- "message": "Network Timeout",
- "severity": "error"
}
], - "current_errors": [
- {
- "code": "50102",
- "id": "CERT_NET04",
- "message": "Network Timeout",
- "severity": "error"
}
]
}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. Only the findings the monitor's profile alerts on are included, and a finding dismissed on the monitor is left out.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "cert.error.resolve",
- "event_date": "2025-12-29T18:30:27+00:00",
- "monitor": {
- "sid": "CMd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "example.com",
}, - "resolved_errors": [
- {
- "code": "50102",
- "id": "CERT_NET04",
- "message": "Network Timeout",
- "severity": "error"
}
], - "current_errors": [
- {
- "code": "50102",
- "id": "CERT_NET04",
- "message": "Network Timeout",
- "severity": "error"
}
]
}Triggered when the monitor's certificate changes (its SHA-256 fingerprint differs from the one last alerted on), including a renewal, when the monitor's profile alerts on certificate changes. When a renewal brings the certificate out of its expiration warning while other errors remain, the event carries expiry_resolved: true (a renewal that clears everything also sends cert.expiration.resolve). Changes while the certificate is flapping are reported by cert.flapping instead.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
| expiry_resolved | boolean Present, and |
| new_fingerprint required | string The SHA-256 fingerprint of the new certificate. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "cert.changed",
- "event_date": "2025-12-29T18:30:27+00:00",
- "monitor": {
- "sid": "CMd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "example.com",
}, - "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",
- "expiry_resolved": true,
- "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"
}Triggered when the monitor's certificate keeps changing between checks: it changed at least three times over the monitor's last five checks that read a certificate, usually because the addresses or nodes behind the hostname serve different certificates. Sent once per episode, when the monitor's profile alerts on certificate flapping; while it lasts, certificate changes aren't sent, and an expiration threshold reached meanwhile is sent once it's over.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
| flap_count required | integer How many times the certificate changed over the monitor's last five checks that read one. |
| stable_fingerprint required | string The SHA-256 fingerprint of the certificate last alerted on for this monitor. |
| alt_fingerprint required | string The SHA-256 fingerprint of the other certificate the latest check read. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "cert.flapping",
- "event_date": "2025-12-29T18:30:27+00:00",
- "monitor": {
- "sid": "CMd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "example.com",
}, - "flap_count": 3,
- "stable_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",
- "alt_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"
}Triggered when a monitor that was flapping has read the same certificate on its last three checks, after a cert.flapping event was sent for it.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
| stable_fingerprint required | string The SHA-256 fingerprint of the certificate the last three checks all read. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "cert.flapping.resolve",
- "event_date": "2025-12-29T18:30:27+00:00",
- "monitor": {
- "sid": "CMd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "example.com",
}, - "stable_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"
}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.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "agent.timeout",
- "event_date": "2025-12-29T18:30:27+00:00",
- "agent": {
- "sid": "AGd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "Production Agent"
}, - "instances": [
- {
- "identifier": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
- "remote_ip": "203.0.113.42",
- "remote_internal_ip": "10.0.1.42",
- "date_last_polled": "2025-12-29T18:15:27+00:00"
}
], - "timeout_minutes": 15
}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.
| X-Webhook-Signature required | string Example: t=1738900000,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd HMAC-SHA256 signature for verifying webhook authenticity. Format: |
| 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. |
{- "event_sid": "TA67bca97cf42743beac24264790faf6dd",
- "event_type": "agent.timeout.resolve",
- "event_date": "2025-12-29T18:30:27+00:00",
- "agent": {
- "sid": "AGd6e9a7963d99482fbf00ce5d100a1de3",
- "name": "Production Agent"
}, - "instances": [
- {
- "identifier": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
- "remote_ip": "203.0.113.42",
- "remote_internal_ip": "10.0.1.42",
- "date_last_polled": "2025-12-29T18:15:27+00:00"
}
], - "timeout_minutes": 15
}