Skip to main content
Version: 0.8

Alerts & thresholds

Alerts are configured per workspace. You define threshold days (for example 30, 14, 7, 1, 0) and choose channels and recipients via contact groups. Each token delivers to its assigned contact group, or the workspace default contact group when none is assigned. 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: high-availability delivery system resilient to failures. 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. All channels are available regardless of plan; self-hosted TokenTimer has no plan tiers.
  • 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; those outside the window are deferred until the next window opens. Defaults to 00:00-23:59 UTC (all day, effectively disabled). (TokenTimer Cloud defaults to 07:00-18:00 UTC instead.)

  • 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 1 hour later (configurable)

Default workspace thresholds​

Thresholds define on which days relative to the token's expiration date a notification is sent. Common values are 30, 14, 7, 1, 0 (day of expiry) and optionally +1 or +7 for post-expiry follow-ups.

  • Pre-expiry: reminders before the date help schedule renewals.
  • Day 0: final day-of-expiry notification.
  • Post-expiry: optional follow-ups to keep expired tokens visible until remediation.
  • Overrides: contact groups may define their own thresholds policy. A token assigned to such a group uses the group thresholds instead of the workspace defaults.
  • Change impact: updating workspace defaults affects tokens without a group thresholds override.

Channels​

Choose which channels to enable and where to deliver notifications:

  • Email: recipients come from the selected contact group.
  • 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. Setup and payload formats are covered in Contact groups & channels.
  • WhatsApp: recipients come from workspace contacts selected in the contact group. 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. Usage counters are informational in self-hosted (no delivery quotas).

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, automatically scheduled within your delivery window.
  • Token selection: includes all tokens within your highest alert threshold (for example, if 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 a contact group to receive alerts. This is set on the auto-created SSL token.
  • If no contact group is selected, the workspace default contact group is used automatically.
  • You can change the contact group later by editing the SSL token directly.