Skip to content

Signal Notifications

Overview

Watchtower uses Shoutrrr's Signal service to send Signal notifications.

Signal notifications require a Signal API server that can send messages on behalf of a registered Signal account. This is typically done using signal-cli-rest-api or secured-signal-api.

Examples

services:
  watchtower:
    image: ghcr.io/sidneyojr/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATION_URL: signal://localhost:8080/+1234567890/+0987654321
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/sidneyojr/watchtower \
  --notification-url "signal://localhost:8080/+1234567890/+0987654321"

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATION_URL=signal://localhost:8080/+1234567890/+0987654321 \
  ghcr.io/sidneyojr/watchtower

Setting up a Signal API Server

  1. Phone Number: A dedicated phone number registered with Signal
  2. API Server: A server running signal-cli with REST API capabilities
  3. Account Linking: Linking the server as a secondary device to your Signal account
  4. Optional Security Layer: Authentication and endpoint restrictions via a proxy

The server must be able to receive SMS verification codes during initial setup and maintain a persistent connection to Signal's servers.

Shoutrrr's Signal URL Format

signal://[user:password@]host:port/source_phone/recipient1/recipient2

Parameters

  • host: Signal API server hostname or IP address
  • port: Signal API server port (default: 8080)
  • user: Username for HTTP Basic Authentication (optional)
  • password: Password for HTTP Basic Authentication (optional)
  • source_phone: Your Signal phone number with country code (e.g., +1234567890)
  • recipient1, recipient2: Phone numbers or group IDs to send to

TLS Configuration

  • Use signal:// for HTTPS (default, recommended)
  • Use signal://...?disabletls=yes for HTTP (insecure, for local testing only)

Attachments

The Signal service supports sending base64-encoded attachments:

shoutrrr send "signal://localhost:8080/+1234567890/+0987654321" \
  "Message with attachment" \
  --attachments "base64data1,base64data2"

Note

Attachments must be provided as base64-encoded data. The API server handles MIME type detection and file handling.

Examples

Send to a single phone number:

signal://localhost:8080/+1234567890/+0987654321

Send to multiple recipients:

signal://localhost:8080/+1234567890/+0987654321/+1123456789/group.testgroup

Send to a group:

signal://localhost:8080/+1234567890/group.abcdefghijklmnop=

With authentication:

signal://user:password@localhost:8080/+1234567890/+0987654321

With API token (Bearer auth):

signal://localhost:8080/+1234567890/+0987654321?token=YOUR_API_TOKEN

Using HTTP instead of HTTPS:

signal://localhost:8080/+1234567890/+0987654321?disabletls=yes