Webhooks
Send certificate alerts to any URL you control, as JSON or formatted natively for Slack and Microsoft Teams. Expiry, health and CT alerts all included.
A webhook delivers every alert to a URL of your choice, in addition to e-mail. Available on the Pro plan, which includes up to 10 webhooks — the ops channel in Slack, a PagerDuty bridge and a customer's own receiver can all get every alert at once.
Setting it up
- Go to Settings → Webhooks.
- Under Add a webhook, give it a name if you like, and paste the URL — your own endpoint, or the incoming-webhook URL from Slack or Teams.
- Choose the payload format that matches where the URL points (see below).
- Click Add webhook.
- Click Send test beside it. A sample alert in the chosen format arrives at the URL, so you can see exactly what a real alert will look like.
Repeat for each place alerts should go. Edit changes a webhook's URL, format or name; switching off Send alerts to this webhook pauses it and keeps its settings and history; Delete removes it. The delivery log underneath shows which webhook each alert went to and what it answered.
Slack, Teams, Discord, Mattermost and Telegram
Pick the format that matches the URL:
- Slack: a Slack message, colour-coded by severity, with the domain, status, days remaining and issuer as fields. Use with a Slack incoming webhook URL.
- Microsoft Teams: a card with the same information. Use with a Teams incoming webhook URL.
- Discord: an embed in the same colours. Use with a channel's webhook URL (Server settings → Integrations → Webhooks).
- Mattermost: the Slack-style message; Mattermost incoming webhooks accept it as is.
- Telegram: a plain-text message from your own bot. Create one with @BotFather, add it to the
chat, and use
https://api.telegram.org/bot<token>/sendMessage?chat_id=<chat id>as the URL. The URL contains the bot token, so treat it like a password. - CertWatchr JSON: the plain format below, for your own endpoint.
The format matters: Slack, Teams and the others silently ignore fields they do not recognise, so sending the plain JSON to a Slack URL produces an empty message rather than an error. If the test arrives blank, the format is wrong.
The JSON payload
One POST per alert with a JSON body:
{
"event": "expiry_warning",
"hostname": "example.com",
"days_remaining": 12,
"cert_expiry": "2026-07-31T23:59:59",
"status": "warning"
}
A ct_new_cert alert adds a ct object with new_count and a certs list (up to ten), each
with serial_number, issuer, common_name, not_before, not_after and observed_at.
event is one of:
event |
Meaning |
|---|---|
expiry_warning |
The certificate is inside your alert threshold. |
expiry_critical |
7 days or fewer left. |
renewal_overdue |
A short-lived certificate is well past its usual automatic-renewal point. |
caa_blocks_issuer |
DNS CAA no longer allows the CA that issued the certificate; the next renewal will fail. |
registration_expiring |
The registered domain expires at its registrar within 30 days (RDAP). |
endpoint_mismatch |
The addresses behind the hostname do not all serve the same certificate. |
cert_changed |
The certificate served changed since the last check. |
check_error |
The host could not be checked, even after retries. |
ct_new_cert |
A new certificate for the hostname appeared in a CT log — see CT log monitoring. |
Delivery
- The same once-per-day spacing as e-mail: one alert of each kind per domain per 24 hours.
- Requests carry
Content-Type: application/jsonand no authentication headers. They are not signed. If you need to make sure requests really come from CertWatchr, put a long random token in the URL path (https://hooks.example.com/cw/<random-32-chars>) and check it on your side. - Your endpoint has 10 seconds to answer. Reply with a 2xx status quickly and do any further work afterwards.
- A failed delivery is not retried. It is recorded on the Alerts page with the HTTP status and error it got, so a broken endpoint is visible rather than silently missed.
Minimal receiver
from flask import Flask, request
app = Flask(__name__)
@app.post("/cw")
def receive():
data = request.json
if data["event"] in ("expiry_warning", "expiry_critical"):
notify_team(data["hostname"], data["days_remaining"])
return "", 200
Several webhooks
Every webhook receives every alert, each in its own format. A webhook that was unreachable when an alert went out gets it at the next check, even if the others already have it; one that has it does not get it twice within the alert's cooldown.
Webhooks belong to the account, not to a domain. Every payload includes the hostname, so if you route alerts for different customers to different places, do the routing at your endpoint by hostname. See Monitoring certificates for customers and projects.
If your plan changes to one without webhooks, they stop receiving alerts but stay on the page, so you can delete them or pick up where you left off after upgrading again.