Frigate Alerts

Animated GIF notifications from Frigate NVR events. Get instant push notifications with a preview GIF of what triggered the alert, not just a still image.

Why?

Frigate generates animated preview GIFs for every detection event, but existing notification tools only send still snapshots. This project sends the actual animated GIF so you can see what happened at a glance.

Features:

• Animated GIF, snapshot, or video clip notifications (configurable per instance)
• 7 notification providers: Pushover, Discord, Telegram, Ntfy, Gotify, Email (SMTP), Webhook
• Zero dependencies - works out of the box with just a Frigate URL
• Optional MQTT for faster delivery (with automatic API fallback)
• Web UI for configuration - no YAML editing required
• Event video page with embedded player (linked from notifications)
• Snooze buttons in Pushover notifications
• Discord rich embeds with color, fields, and timestamps
• Customizable message templates with variables
• Per-camera Pushover sound and priority overrides
• Cooldown per camera to prevent notification spam
• Zone allow/block filtering
• Quiet hours (suppress during sleep)
• Notification history with timestamps and status
• Auto-cleanup of old history records
• Docker healthcheck endpoint
• Single Docker container, minimal resource usage

How It Works

Frigate Alerts has two ways to detect events, and both can run at the same time:

Mode	Speed	Requirements	Setup
API Polling (default)	~10 seconds	Just Frigate URL	Zero config
MQTT (optional)	Instant	MQTT broker details	Add broker in settings

By default, only API polling is used. It queries Frigate's API every 10 seconds for new completed alerts. This means you don't need an MQTT broker, and it doesn't touch your Home Assistant or any other system.

If you add MQTT, both modes run simultaneously. MQTT delivers instantly, and the API poller acts as an automatic fallback if MQTT ever disconnects. Events are deduplicated so you'll never get double notifications.

                               +--- MQTT (optional, instant) ---+
Frigate NVR --+                                                  +-->  Frigate Alerts --> Notifications
                               +--- API Polling (default) ------+
                                                                          |
                                                               Fetches preview.gif
                                                               from Frigate API

1. Frigate Alerts detects completed alert reviews (via API polling and/or MQTT)
2. Filters by camera, label, and zone based on your settings
3. Waits briefly for Frigate to generate the preview GIF
4. Fetches the media from Frigate's API (GIF, snapshot, or video clip)
5. Sends it as an attachment to all enabled providers
6. Falls back to a snapshot image if the GIF isn't available

Supported Providers

Provider	GIF Support	Features
Pushover	Animated GIF	Multiple recipients, priority levels, custom sounds, per-camera overrides, snooze buttons
Discord	Animated GIF	Multiple webhooks, rich embeds with color and fields
Telegram	Animated GIF	Bot API, sendAnimation/sendPhoto/sendVideo
Ntfy	Attached image	Self-hosted or ntfy.sh, token auth
Gotify	Link only	Self-hosted, priority levels, markdown
Email (SMTP)	Attached image	Multiple recipients, TLS, any SMTP server
Webhook	JSON payload	Custom URL, headers, POST/PUT method, full event data

Quick Start

1. Deploy the container

services:
  frigate-alerts:
    container_name: frigate-alerts
    build: https://github.com/ryzendigo/frigate-alerts.git
    restart: unless-stopped
    ports:
      - "8085:8000"
    volumes:
      - ./config:/app/config
    networks:
      - your-frigate-network  # Same network as your Frigate container

2. Open the web UI

Go to http://your-host:8085 and configure:

• Frigate URL - the internal URL where this container can reach Frigate (e.g. http://frigate:5000)
• At least one notification provider - enable and configure Pushover, Discord, etc.
• Click Save

That's it. Notifications will start flowing on the next alert.

3. (Optional) Add MQTT for instant delivery

If you have an MQTT broker (Home Assistant, Mosquitto, etc.), enable MQTT in settings and add the broker details. This won't affect your existing MQTT setup - Frigate Alerts is just a passive subscriber.

4. (Optional) Set up event video pages

If you expose Frigate Alerts publicly (or via reverse proxy), set the Alerts Public URL in settings. This enables:

• Event video pages with an embedded player (linked from notifications)
• Snooze buttons in Pushover notifications

Alternative Install Methods

Docker Run

docker run -d \
  --name frigate-alerts \
  -p 8085:8000 \
  -v $(pwd)/config:/app/config \
  --network your-frigate-network \
  ghcr.io/ryzendigo/frigate-alerts:latest

Build from Source

git clone https://github.com/ryzendigo/frigate-alerts.git
cd frigate-alerts
docker build -t frigate-alerts .
docker run -d -p 8085:8000 -v $(pwd)/config:/app/config frigate-alerts

Configuration

Everything can be configured through the web UI. Or edit config/config.yml directly - copy config/config.example.yml to get started:

frigate:
  url: http://frigate:5000
  public_url: https://frigate.example.com  # for links in notifications

# Optional - leave disabled to use API polling only
mqtt:
  enabled: false
  server: 10.0.0.1
  port: 1883
  username: mqtt
  password: your_password

cameras: []   # empty = all cameras
labels:
  - person

gif_delay: 10  # seconds to wait for GIF generation

pushover:
  enabled: true
  token: your_app_token
  recipients:
    - name: User
      userkey: your_user_key

See config/config.example.yml for the full list of options including all providers.

Message Templates

Customize notification titles and messages using variables:

Variable	Example
{camera}	front_door
{label}	Person
{zone}	driveway
{time}	14:30:00
{date}	2025-01-15

Default title: {label} - {camera} Default message: Person detected on front_door (driveway)

Provider Setup

Pushover

1. Create an app at pushover.net/apps and note the API Token
2. Find your User Key on the Pushover dashboard
3. Animated GIFs require Pushover client v3.4+
4. Per-camera overrides let you set different sounds/priorities (e.g. doorbell = emergency)

Discord

1. In your Discord server, go to Server Settings > Integrations > Webhooks
2. Create a webhook and copy the URL

Telegram

1. Create a bot with @BotFather and get the bot token
2. Get your chat ID by messaging @userinfobot

Ntfy

1. Use ntfy.sh or self-host ntfy
2. Pick a topic name (or create one with a token for auth)

Gotify

1. Self-host Gotify and create an application
2. Use the application's token

Email (SMTP)

1. Use any SMTP server (Gmail, Outlook, self-hosted)
2. For Gmail, use an App Password

Webhook

1. Point to any HTTP endpoint that accepts JSON
2. Payload includes: title, message, url, image_type, event data (review_id, event_id, camera, label, zones, video_url)

API Endpoints

Endpoint	Method	Description
/	GET	Web UI
/event/{event_id}	GET	Event video/media page
/api/config	GET	Get current configuration
/api/config	POST	Update configuration
/api/history	GET	Notification history (?limit=50)
/api/status	GET	Connection status (Frigate, poller, MQTT)
/api/test	POST	Send test notification using latest event
/api/snooze	POST	Snooze notifications ({"minutes": 30})
/api/snooze/cancel	POST	Cancel active snooze
/api/snooze/quick	GET	Quick snooze via URL (?minutes=30)
/api/health	GET	Health check endpoint

Requirements

• Frigate NVR (v0.14+)
• Docker
• That's it. No MQTT broker required.

License

MIT