Skip to main content
Version: 0.10

Contact groups & channels

Contact groups are named recipient lists per workspace. Each token delivers alerts to its assigned contact group, or to the workspace default group when none is assigned. Groups combine per-contact channels (email, WhatsApp), named webhooks, and an optional thresholds override.

  • Per-contact channels: select Email and/or WhatsApp for each contact from the workspace contacts list. Email uses the contact's email; WhatsApp uses the contact's phone number.
  • Webhooks: select named webhooks from the workspace webhook list.
  • Thresholds override: optionally set group-specific thresholds that override workspace defaults.
  • Default group: set a workspace default; tokens without an explicit group use the default.
  • Per-token assignment: assign a contact group when creating or editing a token.
  • Caps: self-hosted TokenTimer has no plan tiers, so there are no caps on the number of contact groups or members per group.

Workspace contacts​

Contacts are people who can receive alerts. Add them once per workspace, then select them in contact groups.

  • Add contacts: first name, last name, and at least a valid email or E.164 phone number (for example +14155550100). Optional details: department, title, note.
  • Test contacts: use the Test button to send a test WhatsApp message (2-minute cooldown per number).
  • Select in groups: in the contact group editor, check which contacts should receive alerts and on which channels.

WhatsApp​

WhatsApp requires a Twilio account configured at the deployment level; see Admin setup: Twilio WhatsApp for connecting your Twilio credentials. Once configured, add workspace contacts with phone numbers, then select them in contact groups.

  • No fallback: if a contact group has no contacts selected for WhatsApp, WhatsApp alerts are not sent.
  • Operational limits: provider throttling and Twilio delivery backoff still apply regardless of self-hosting.

WhatsApp templates setup​

This section is the exact setup contract between TokenTimer and Twilio Content Templates. If a template uses placeholders that TokenTimer does not send, Twilio rejects delivery.

Step 1: Create templates in Twilio​

  • Twilio Console > Messaging > Content Template Builder > Create template.
  • Content type: Text.
  • Channel: WhatsApp.
  • Category: Utility (recommended for alerts and digests).
  • Create one template per use case below. Save and submit for approval. Copy the generated HX... SID.

Step 2: Map each SID​

  • TWILIO_WHATSAPP_ALERT_CONTENT_SID_EXPIRES: template used for upcoming expirations. Configured in System Settings.
  • TWILIO_WHATSAPP_ALERT_CONTENT_SID_EXPIRED: template used for already expired items. Configured in System Settings.
  • TWILIO_WHATSAPP_TEST_CONTENT_SID: template used by System Settings test send and contact test send. Configured in System Settings.
  • TWILIO_WHATSAPP_WEEKLY_DIGEST_CONTENT_SID: template used for the weekly digest channel. Configured in System Settings.
  • TWILIO_WHATSAPP_ALERT_CONTENT_SID_ENDPOINT_DOWN: deployment-level template used for endpoint down alerts. Configured as an environment variable; see Configuration reference.
  • TWILIO_WHATSAPP_ALERT_CONTENT_SID_ENDPOINT_RECOVERED: deployment-level template used for endpoint recovered alerts. Configured as an environment variable; see Configuration reference.

Endpoint health WhatsApp template SIDs are configured at deployment level and require a delivery worker restart after changes.

Placeholder contracts by template​

  • EXPIRES template: recipient_name, token_type, token_name, days_text, expiration_date, details.
  • EXPIRED template: recipient_name, token_type, token_name, days_text, expiration_date, details.
  • TEST template: no placeholders required.
  • WEEKLY_DIGEST template: recipient_name, workspace_name, contact_group_name, tokens_count, tokens_list.
  • ENDPOINT_DOWN template: recipient_name, endpoint_name, endpoint_url, token_name, detected_at.
  • ENDPOINT_RECOVERED template: recipient_name, endpoint_name, endpoint_url, token_name, detected_at.

Rule: only use placeholders listed for that template. Extra placeholders are not populated by TokenTimer.

Copy-ready template examples​

EXPIRES​

Template body

ALERT: Token Expiring Soon

Hello {{recipient_name}}, your {{token_type}} token "{{token_name}}" is expiring in {{days_text}} day(s) on {{expiration_date}}.

Details: {{details}}

Please plan the renewal to avoid service disruption.

TokenTimer Expiration Management

Example sample values

recipient_name = Operations Team
token_type = Certificate
token_name = production-api-cert
days_text = 7
expiration_date = 2025-10-10
details = DigiCert, Location: eu-west-1 (AWS), Used By: API Gateway, Domains: api.example.com, www.example.com, Algorithm: RSA, Key Size: 2048 bits
EXPIRED​

Template body

URGENT: Token Expired

Hello {{recipient_name}}, your {{token_type}} token "{{token_name}}" expired {{days_text}} day(s) ago on {{expiration_date}}.

Details: {{details}}

This token has expired and may cause service outages. Please renew immediately.

TokenTimer Expiration Management

Example sample values

recipient_name = Operations Team
token_type = Certificate
token_name = production-api-cert
days_text = 3
expiration_date = 2025-10-10
details = DigiCert, Location: eu-west-1 (AWS), Used By: API Gateway, Domains: api.example.com, www.example.com, Algorithm: RSA, Key Size: 2048 bits
TEST​

Template body

TokenTimer WhatsApp Test

Hello, this is a test to confirm WhatsApp alerts are working for your workspace.

If you receive this, WhatsApp delivery is configured correctly.

TokenTimer Expiration Management

No sample values required. This template is static.

WEEKLY_DIGEST​

Template body

📊 Weekly Digest: {{tokens_count}} token(s) Expiring Soon

Hello {{recipient_name}},

Your workspace "{{workspace_name}}" has {{tokens_count}} token(s) expiring soon in the contact group "{{contact_group_name}}".

Expiring tokens
{{tokens_list}}

Please review and renew these tokens to avoid service disruptions.

TokenTimer Expiration Management

Example sample values

tokens_count = 10
recipient_name = On-call Team
workspace_name = Production
contact_group_name = Primary On-call
tokens_list = SSL Certificate: 2025-10-10 (90d); API Key: 2025-11-29 (75d); Database Password: 2025-11-19 (71d)
ENDPOINT_DOWN​

Template body

⚠️ Endpoint Down

Hello {{recipient_name}},

TokenTimer detected that endpoint "{{endpoint_name}}" is DOWN.
URL: {{endpoint_url}}
Linked token: {{token_name}}
Detected at: {{detected_at}}

Please check the affected service.

TokenTimer Endpoint Monitoring

Example sample values

recipient_name = On-call Team
endpoint_name = staging-api
endpoint_url = https://staging.example.com/health
token_name = staging-api-cert
detected_at = Mar 16, 2026, 18:00 UTC
ENDPOINT_RECOVERED​

Template body

✅ Endpoint Recovered

Hello {{recipient_name}},

TokenTimer detected that endpoint "{{endpoint_name}}" has RECOVERED.
URL: {{endpoint_url}}
Linked token: {{token_name}}
Detected at: {{detected_at}}

The endpoint is responding normally again.

TokenTimer Endpoint Monitoring

Example sample values

recipient_name = On-call Team
endpoint_name = staging-api
endpoint_url = https://staging.example.com/health
token_name = staging-api-cert
detected_at = Mar 16, 2026, 18:12 UTC

Webhooks​

Webhooks deliver alerts to Slack, Microsoft Teams, Discord, PagerDuty, or any generic HTTPS endpoint. Available on all self-hosted deployments regardless of plan.

  • Named webhooks: create each webhook once with a required name, then reference it from one or many contact groups. Up to 5 webhooks per workspace.
  • Provider host validation: for the Slack, Teams, Discord, and PagerDuty kinds, the URL host must belong to the official provider domain (for example hooks.slack.com, webhook.office.com, discord.com, events.pagerduty.com); other hosts are rejected with WEBHOOK_HOST_NOT_ALLOWED. Use the generic kind for any other HTTPS endpoint.
  • Verification: webhooks are verified with a test delivery before use. Test sends are rate limited (a few per minute with a short cooldown between attempts).
  • Retry: failed webhook deliveries appear in the alert queue and can be retried from there.

Slack​

Create an incoming webhook in your Slack workspace and paste the https://hooks.slack.com/services/... URL. TokenTimer sends Slack-formatted messages with the token name, workspace, expiry date, and days remaining.

Microsoft Teams​

Create an incoming webhook connector (or a Workflows webhook) on the target channel and paste the URL. TokenTimer sends a Teams-compatible card with the token details.

Discord​

Create a webhook in the channel settings (Integrations → Webhooks) and paste the https://discord.com/api/webhooks/... URL. TokenTimer sends a Discord-formatted embed with the token details.

PagerDuty​

Use a PagerDuty Events API v2 integration key (a 32-character alphanumeric routing key). TokenTimer triggers an event with the token name and expiry details so your escalation policies take over. PagerDuty is not supported for weekly digests.

Generic HTTPS endpoint​

Any HTTPS endpoint can receive alert deliveries as JSON with the generic kind (the provider host validation above applies only to the named kinds). Use this for internal tooling, automation, or chat systems not listed above.