Overview

Snapp supports optional third-party integrations that enhance visibility and security without becoming hard dependencies.

Integrations are:

  • host-scoped
  • runtime-configurable
  • fully optional
  • non-blocking for redirects

At the moment, Snapp provides first-class support for:

  • Umami — operational and visit analytics
  • VirusTotal API — domain reputation and abuse prevention

Both are configured per host via settings.yaml or the admin UI.

Design principles

Integrations in Snapp follow strict rules:

  • core redirect flow must continue even if an integration is unavailable
  • failures are logged, never fatal
  • configuration is isolated per host (organization)
  • no integration can escalate privileges or bypass policies

Snapp treats integrations as observers, not authorities.

Umami integration

Purpose

Umami is used for operational analytics, not as the primary metrics engine.

It tracks:

  • resolved redirects
  • invalid shortcodes
  • invalid secret attempts
  • failed login attempts
  • database unavailability events

This provides visibility into system behavior and abuse patterns.

How Umami is embedded

Snapp uses the official @umami/node client.

For each request:

  1. The active host is resolved
  2. The host’s Umami configuration is loaded
  3. A scoped Umami client is created
  4. Events are sent server-side (SSR)

No client-side script is injected by Snapp itself.

Events tracked

Examples of tracked events:

  • successful redirect visits
  • 404 shortcodes
  • invalid password attempts on protected URLs
  • failed authentication attempts
  • backend availability issues

Each event includes:

  • hostname
  • language
  • referrer
  • resolved URL
  • shortcode
  • website id

Tracking is best-effort. Failures are ignored.

Visit correlation

When a redirect succeeds:

  • Umami receives a tracking event
  • Snapp writes its own metric row

These are independent paths.

If Umami is down:

  • Snapp metrics still work
  • redirect still happens

Configuration

Per host:

thirdparty:
  umami:
    url: https://umami.example.org
    websiteId: <uuid>

Both fields must be present to enable Umami.

Removing the configuration disables it immediately.

VirusTotal API integration

Purpose

VirusTotal is used to validate target domains at redirect time.

It prevents:

  • known malicious domains
  • phishing destinations
  • URLs flagged by external reputation systems

VirusTotal does not replace internal watchlists. It complements them.

How checks are performed

During redirect resolution:

  1. The target domain is extracted
  2. Local watchlists are evaluated
  3. VirusTotal reputation is queried (if enabled)
  4. A decision is made before redirect

If a domain fails validation:

  • redirect is blocked
  • no metric is written
  • no Umami visit is recorded

Failure handling

VirusTotal is treated as advisory:

  • network errors do not crash redirects
  • API failures are logged (debug mode)
  • missing API key disables checks silently

Snapp never retries indefinitely or blocks startup.

Configuration

Per host:

thirdparty:
  vtapi:
    apikey: <your_api_key>

The key is stored encrypted at rest and never exposed publicly.

Removing the key disables VirusTotal checks immediately.

Host-scoped behavior

Integrations are resolved per host:

  • different domains can use different Umami instances
  • some hosts may enable VirusTotal, others not
  • changes invalidate in-memory caches immediately

There is no global integration state.

Admin UI integration

Both integrations can be managed from the Settings → Integrations panel.

Capabilities:

  • enable / disable integrations
  • update credentials
  • validate input
  • apply changes live
  • remove integrations cleanly

All changes persist to settings.yaml and reload at runtime.

Security and isolation

Integrations:

  • do not receive internal IDs
  • do not receive authentication tokens
  • cannot modify database state
  • cannot bypass organization boundaries

They observe events already allowed by policy.

What integrations do NOT do

  • No redirect is delegated to a third party
  • No authority is outsourced
  • No request is blocked due to integration downtime
  • No data is shared across hosts

Snapp remains functional without any integration enabled.