UniFi Access Badge-In Dashboard (V3)

A Dockerised Flask + SQLite web app that receives UniFi Access access.door.unlock webhooks, resolves UUIDs to real user names via the UniFi Access API, and displays a modern dark attendance dashboard with on-time / late status, first + latest badge times, and a test reset button.

Features

Receives webhooks from the UniFi Access developer API or legacy Alarm Manager format.
Resolves UUIDs to real names via the UniFi Access REST API (cached in SQLite, refreshed every 6 hrs).
First badge in column — never overwritten by subsequent badges.
Latest badge in column — shows the most recent entry that day.
Sync Users button — manually refreshes the user name cache.
Reset Day button — confirmation modal deletes all records for the selected date (testing only).
Green ON TIME / Red LATE status chips based on a configurable cutoff time.
Fully Dockerised — single container, persistent SQLite volume.

Project layout

.
├── app.py
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── .gitignore
└── static/
    └── index.html

Setup

1. Generate a UniFi Access API token

Open UniFi OS → UniFi Access → Settings → Integrations / Developer API.
Create a new API Key (Bearer Token) and copy it.

2. Create your .env file

cp .env.example .env
# edit .env and fill in UNIFI_HOST and UNIFI_API_TOKEN

3. Register the webhook with UniFi Access (run once)

curl -k -X POST "https://192.168.1.1:45/api1/webhooks/endpoints" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dashboard Unlock Events",
    "endpoint": "http://YOUR_UNRAID_IP:8000/api/unifi-access",
    "events": ["access.door.unlock"],
    "headers": { "X-Source": "unifi-access" }
  }'

Verify registration:

curl -k -X GET "https://192.168.1.1:45/api1/webhooks/endpoints" \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"

4. Deploy on Unraid

cd /mnt/user/appdata
git clone https://github.com/<your-user>/<your-repo>.git unifi-access-dashboard
cd unifi-access-dashboard
cp .env.example .env && nano .env
docker compose up -d --build

Open: http://<UNRAID-IP>:8000/

5. Updating from GitHub

cd /mnt/user/appdata/unifi-access-dashboard
git pull
docker compose up -d --build

API endpoints

Method	Path	Description
POST	`/api/unifi-access`	Receives webhook from UniFi Access
GET	`/api/first-badge-status`	Returns first + latest badge per user for a date
GET	`/api/sync-users`	Triggers immediate user cache sync
DELETE	`/api/reset-day?date=YYYY-MM-DD`	Deletes all records for the given date

Troubleshooting

Symptom	Cause	Fix
Names show as `Unknown (UUID…)`	Users not cached yet	Click Sync Users
Webhook not arriving	Firewall / port	Ensure port 8000 reachable from controller
SSL error on curl	Self-signed cert	Use `-k` flag
404 on `/api1/users`	Firmware path differs	Try `/api/v1/users`
Duplicate events	Both Alarm Manager and API webhooks active	Remove one or deduplicate by event ID

3.2 KiB Raw Blame History