Skip to main content
Version: 0.15

Alerts & thresholds

Alerts are configured per workspace. You define threshold days (for example 30, 14, 7, 1, 0, and optionally negative post-expiry values) and choose channels and recipients via contact groups. Each token delivers to its assigned contact groups, or the workspace default contact group when none are assigned. For a given threshold window, only groups whose effective thresholds include that window receive that alert (recipients and channels are the union of those matching groups). When a token approaches or passes an expiration threshold (once per threshold), TokenTimer queues notifications and delivers the alert to the configured channels.

  • Scope: settings apply to all tokens inside the workspace.
  • Delivery: failed deliveries are retried automatically. Every attempt (success or failure) is visible in the alert queue and usage metrics, and failed webhooks can be retried manually.
  • Channels: Email, webhooks (Slack, Teams, Discord, PagerDuty, generic), and WhatsApp with workspace contacts. WhatsApp requires Twilio at the deployment level.
  • Caps: no delivery quotas or monthly caps in self-hosted. Usage counters shown in the dashboard are informational only.

Workspace delivery window​

Configure when alerts and weekly digests can be delivered across all channels (email, webhooks, WhatsApp). Alerts and digests are sent only during this delivery window. Alerts outside the window are deferred until the next window opens; the Monday weekly-digest cron is skipped (not deferred) if it falls outside the window. Defaults to 00:00-23:59 UTC (all day).

  • Start/end time: HH:mm format (for example 08:00, 18:00)
  • Timezone: select from 40+ IANA timezones (for example Europe/Zurich, America/New_York)
  • Applies to: all alert channels (email, webhooks, WhatsApp)
  • Validation: strict HH:mm format enforced; invalid values are rejected
  • Midnight wrapping: if start > end (for example 22:00 to 06:00), the window wraps overnight
  • Deferral: alerts outside the window are retried about 3 hours later by default (DELIVERY_WINDOW_DEFERRAL_MS). The interval is configurable.

Default workspace thresholds​

Thresholds are whole-number days relative to the token's expiration date, in the range -365 to 730. Positive values fire before expiry (for example 30, 14, 7, 1). 0 is the day of expiry. Negative thresholds fire after expiry: for example -1 is one day after expiry and -7 is seven days after. The UI shows post-expiry follow-ups as "Nd after"; operators enter negative integers (for example -1, -7). Searching for "negative threshold" in ops notes means those post-expiry integers.

  • Pre-expiry: reminders before the date help schedule renewals.
  • Day 0: final day-of-expiry notification.
  • Post-expiry (negative thresholds): optional follow-ups to keep expired tokens visible until remediation.
  • Overrides: contact groups may define their own thresholds policy. A token assigned to one or more groups uses the union of each group's effective thresholds (group override when set, otherwise workspace defaults for that group). Delivery for each window still goes only to groups that include that window.
  • Change impact: updating workspace defaults affects tokens without a group thresholds override.
  • Import catch-up: on file or integration import, alerts for thresholds that have already passed are suppressed so you do not get a storm of overdue notices; alerting resumes at the next future threshold. See Integrations: alert catch-up and Import from file.

Channels​

Choose which channels to enable and where to deliver notifications:

  • Email: Recipients come from the selected contact groups.
  • Webhooks: Create and verify named webhooks for Slack, Microsoft Teams, Discord, PagerDuty, or generic HTTPS endpoints; contact groups reference one or many webhooks to route alerts. Payload formats and setup are covered in Contact groups & channels.
  • WhatsApp: Recipients come from workspace contacts selected in the assigned contact groups. Requires Twilio configuration at the deployment level. See Contact groups & channels and WhatsApp templates setup.

Delivery visibility: successes and failures appear in the alert queue; failed webhooks can be retried from the queue view.

Weekly digest​

The weekly digest sends a summary of all tokens close to expiring (within your thresholds) once per week per contact group, giving you a consolidated view instead of individual alerts for each token.

  • Enable per group: in contact group settings, check "Email weekly digest", "WhatsApp weekly digest", or "Webhook weekly digest".
  • Frequency: sent once per week (on Mondays) per contact group. If that Monday run falls outside your delivery window, it is skipped (not deferred).
  • Token selection: uses the largest workspace threshold that is ≥ 1 (not a union of group-override thresholds). For example, if workspace thresholds are 1, 7, 30, 60 days, the digest shows tokens expiring in 60 days or less. Excludes already expired tokens.
  • Channels: email, WhatsApp, and webhooks (Slack, Discord, Teams, generic). PagerDuty is not supported for digests.

Endpoint health alerts​

When you add an endpoint monitor with health checking enabled, TokenTimer tracks the health status of that URL and alerts you when it goes down or recovers. Alerts are triggered on state transitions only, not on every check.

How it works​

  • First check: the very first health check establishes a baseline. No alert is sent regardless of the result.
  • Healthy to unhealthy: when an endpoint transitions from healthy to unhealthy (HTTP error, timeout), a "down" alert is queued.
  • Unhealthy to healthy: when an endpoint recovers, a "recovered" alert is sent, but only if you were previously notified it was down.
  • No change: if the status stays the same between checks, no new alert is created.

Alert after failures​

To avoid false alarms from brief network glitches, you can configure how many consecutive failures must occur before you are notified. This is the "Alert after failures" setting on each endpoint.

  • Default is 2 consecutive failures.
  • The "down" alert is queued immediately on the first failure transition, but the delivery worker waits until the failure count reaches the threshold before sending the notification.
  • If the endpoint recovers before the threshold is reached, the queued alert is silently discarded and you receive nothing.
  • Recovery alerts are always sent immediately (no threshold gate) if a "down" notification was previously delivered.

No spam guarantee​

  • Only one "down" alert is sent per outage, no matter how long the endpoint stays unhealthy.
  • Only one "recovered" alert is sent when the endpoint comes back online.
  • If an endpoint was never healthy (for example a misconfigured URL), the first check produces no baseline transition. A "down" alert fires only after it eventually becomes healthy and then goes unhealthy again.
  • Recovery alerts are never sent if you were not previously informed of the outage.

Delivery channels and contact groups​

Endpoint health alerts use the same delivery channels configured in your workspace alert settings and respect your delivery window.

  • When adding an endpoint, you can select contact groups to receive alerts. This is set on the auto-created SSL token.
  • If none are selected, the workspace default contact group is used automatically.
  • You can change the assigned groups later by editing the SSL token directly.