Email and Webhooks

Configure integrations in Settings > Notifications. Saved credentials are encrypted with the installation's separate secrets.key; keep that key with SQLite recovery material. Configure and test each channel, then independently enable the channels you want. Scheduling and event selection are covered in Alerts.

Channel configuration

Channel	Supply	Check if a test fails
ntfy	Base URL, topic, optional access token	Topic permission, token, server reachability
Discord	Webhook URL	Valid webhook, destination/channel permissions, rate limits
Gotify	Base URL and application token	Correct application token and server URL
Email	SMTP host/port, sender, recipients, optional account credentials	TLS mode, certificate, account and sender permissions
Generic webhook	Receiver URL, optional bearer token and HMAC secret	Receiver status, raw-body signature verification

The ntfy default base URL is https://ntfy.sh; you may configure your own server. Keep topics, webhook URLs, tokens, and recipient addresses private. GearBeacon sends to the services you configure; it does not provide a hosted relay or require a GearBeacon account.

SMTP transport

SMTP port 465 uses implicit TLS. Other SMTP ports require STARTTLS by default, and credentials are never sent on an unencrypted connection. Certificate validation is enabled by default. Messages use multipart/alternative for HTML and text, multipart/related for inline images, and a unique Message-ID.

Use the mail provider's documented authenticated SMTP host and sender policy. Multiple recipients are comma-separated in SMTP_TO. A configured public dashboard URL provides links back to GearBeacon; the recipient still needs access to that private instance.

Keep STARTTLS and certificate validation enabled. Resolve a hostname, trust-chain, clock, or provider configuration problem instead of turning off certificate checking. See the configuration reference for the corresponding variables.

Email appearance and preview

SMTP email uses responsive, event-specific HTML with a matching plain-text alternative. Restocks, price targets and drops, sellouts, status changes, new products, operational issues, tests, and grouped digests each have a focused layout. Product details are captured when the event is queued, so delayed alerts describe what GearBeacon actually detected. When a public URL is configured, email can link directly back to the matching product in the private dashboard.

Email appearance controls in Settings offer compact, standard, or detailed layouts; device, light, or dark themes; subject prefixes; price calculations; alert explanations; digest limits; and a desktop/mobile preview rendered by the same code used for SMTP. Product images are embedded inline by default from an exact Ubiquiti host allowlist with strict timeout, content-type, and size limits. Image failures fall back cleanly and never prevent the alert from being sent. Messages contain no tracking pixels, scripts, remote fonts, or analytics.

The default layout is standard, theme auto, subject prefix [GearBeacon], and digest display limit 12 unique products (configurable from 1 to 50). Image embedding, explanations, and price calculations default on. Subject prefixes are limited to 60 characters and cannot contain line breaks. Preview desktop and mobile layouts, then use the email test to verify actual provider delivery.

Generic webhook payload

The receiver gets an HTTP POST with Content-Type: application/json. The top-level fields are:

Field	Meaning
source	GearBeacon
version	Application version that sends the message
title / message	Event-specific notification text
event	Queued event and its captured product/collection/operational context
sentAt	ISO timestamp of the delivery attempt

Treat event fields as dependent on the event kind rather than assuming every payload has a product price or SKU. The receiver should return a successful HTTP status promptly; the sender uses a 10-second request timeout. Delivery retries mean a receiver should handle repeats safely.

When configured, bearer authentication uses Authorization: Bearer <token>. HMAC signing adds:

X-GearBeacon-Timestamp: <Unix timestamp in seconds>
X-GearBeacon-Signature: sha256=<hex HMAC-SHA256 digest>

The signed bytes are the timestamp, a literal dot, and the exact raw JSON request body:

HMAC-SHA256(sharedSecret, timestamp + "." + rawBody)

Read the raw body before parsing it, validate the timestamp against a bounded tolerance appropriate for your receiver, recompute the digest, and compare it with a constant-time operation. Do not parse and reserialize JSON before verification: whitespace, escaping, or key-order changes alter the signature. Signing authenticates content; use HTTPS to protect transport confidentiality.

Diagnose delivery

A preview renders/evaluates a notification without sending it. An individual channel test sends a test. For real events, inspect Activity > event details and Settings > Operations for pending, sent, or failed outcomes. Check quiet hours, digest timing, enabled state, and watch/collection rules before treating a delayed or suppressed event as a transport failure.

Implementation: notification delivery and signing, email rendering.