Cert Spotter - Webhooks

Cert Spotter Webhooks

Overview

You can configure Cert Spotter to invoke a webhook when certain events take place.

Notes

Your webhook URL can include a username and password for HTTP Basic Authentication. We recommend you use this to verify that incoming webhooks requests are really from SSLMate.
A webhook request is considered successful if your endpoint returns an HTTP status code in the range 200-299 within 15 seconds.
HTTP redirects are not followed. If your endpoint returns a redirect, it is considered a failure.
If a webhook request fails, we will reach out to you over email and can retry the request at your behest. In the future we will automate the process of retrying requests and notifying you of failures.
It is possible for the same webhook request to be delivered more than once to your endpoint if there is a network problem. If you need to suppress duplicate requests, you can use the Idempotency-Key HTTP header, whose value uniquely identifies the request.

Unknown Certificate Event

When Cert Spotter detects an unknown certificate for one of your monitored domains, we post a JSON object containing the following fields:

id string The ID of the certificate issuance.

html_url string The URL of a web page describing the certificate issuance.

endpoints

array

Your monitored endpoints for which this certificate is valid. Each endpoint is represented by an object with the following fields:

`dns_name`	string	The DNS name of the endpoint
`monitored_domain`	string	The name of the monitored domain object which matches the endpoint
`wildcard`	boolean	True if and only if the endpoint's DNS name corresponds to a wildcard DNS name in the certificate rather than the literal DNS name

issuance object The issuance object describing the certificate. The following fields are expanded: dns_names, issuer, issuer.website, issuer.caa_domains, problem_reporting, cert_der.

Example

If you are monitoring sslmate.com (including subdomains), and Cert Spotter detects an unknown certificate valid for packages.sslmate.com and software.sslmate.com, we will post the following JSON object to your webhook endpoint:

{
  "id": "2715166372",
  "html_url": "https://sslmate.com/console/monitoring/issuances/2715166372",
  "endpoints": [
    {"dns_name":"packages.sslmate.com", "monitored_domain":".sslmate.com", "wildcard":false},
    {"dns_name":"software.sslmate.com", "monitored_domain":".sslmate.com", "wildcard":false}
  ],
  "issuance": {
    "id":"2715166372",
    "tbs_sha256":"4dc65f49ec2b0f1b7120207000d8ed3dd94465e89dfe9210715ddc82a8ff4f18",
    "cert_sha256":"69fb7252f3cd5c052db8325cf82dc40bd72ed01525f2301f804765be8d62ae43",
    "dns_names":["packages.opsmate.com","packages.sslmate.com","software.sslmate.com"],
    "pubkey_sha256":"36487345ef0c9a7aa10047ab32d64c1617f85163120e7d07187aa443729eebb4",
    "issuer": {
      "friendly_name":"Sectigo",
      "website":"https://sectigo.com/",
      "caa_domains":["sectigo.com","comodo.com","comodoca.com","usertrust.com","trust-provider.com"],
      "pubkey_sha256":"e1ae9c3de848ece1ba72e0d991ae4d0d9ec547c6bad1dddab9d6beb0a7e0e0d8",
      "name":"C=GB, ST=Greater Manchester, L=Salford, O=Sectigo Limited, CN=Sectigo RSA Domain Validation Secure Server CA"
    },
    "not_before":"2021-07-13T00:00:00Z",
    "not_after":"2022-08-12T23:59:59Z",
    "revoked":false,
    "problem_reporting":"To revoke one or more certificates issued by Sectigo for which you (i) are the Subscriber or (ii) control the domain or (iii) have in your possession the private key, you may use our automated Revocation Portal here:\u000A  ?? https://secure.sectigo.com/products/RevocationPortal\u000A\u000ATo programatically revoke one or more certificates issued by Sectigo for which you have in your possession the private key, you may use the ACME revokeCert method at this endpoint:\u000A  ?? ACME Directory: https://acme.sectigo.com/v2/keyCompromise\u000A  ?? revokeCert API: https://acme.sectigo.com/v2/keyCompromise/revokeCert\u000A\u000ATo report any other abuse, fraudulent, or malicious use of Certificates issued by Sectigo, please send email to:\u000A  ?? For Code Signing Certificates: signedmalwarealert[at]sectigo[dot]com\u000A  ?? For Other Certificates (SSL/TLS, S/MIME, etc): sslabuse[at]sectigo[dot]com",
    "cert_der":"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"
  }
}

New Endpoint Event (beta)

The new endpoint webhook is in beta, which means we are still soliciting feedback and may make changes to the format in the future. To set up a new endpoint webhook for your account, please send us an email with the URL of your webhook endpoint.

When Cert Spotter detects a new endpoint for one of your monitored domains, we post a JSON object containing the following fields:

`dns_name`	string	The DNS name of the endpoint
`monitored_domain`	string	The name of the monitored domain object which matches the endpoint
`html_url`	string	The URL of a web page showing the endpoint

Example

If you are monitoring sslmate.com (including subdomains), and Cert Spotter detects the subdomain packages.sslmate.com, we will post the following JSON object to your webhook endpoint:

{
  "dns_name":"packages.sslmate.com",
  "monitored_domain":".sslmate.com",
  "html_url": "https://sslmate.com/console/monitoring/packages.sslmate.com"
}