Signal

Send critical outage and recovery alerts through Signal using a secure self‑hosted (or trusted) Signal gateway.

How It Works

Garmingo sends a JSON payload to your provided Signal Gateway (REST) endpoint. The gateway authenticates the request with your API token and forwards the message from the configured sender (phone number) to subscribed recipients through the Signal network (end‑to‑end encrypted beyond the gateway boundary).

Prerequisites

A running Signal gateway / relay (e.g. a REST wrapper around signal-cli).
A registered Signal phone number (sender) linked to that gateway.
An API token generated by (or configured on) the gateway for authenticating inbound requests.
Publicly reachable HTTPS URL (strongly recommended TLS; use a certificate trusted by standard roots).

Setup in Garmingo

Fill the three fields exactly as shown in the UI:

Field	What to Enter	Example
Signal Phone Number	The sender number registered on your gateway (E.164).	`+49123456789`
Signal API URL	Base URL of your Signal gateway endpoint (include protocol + optional port, no trailing slash).	`https://signal.example.com:8080`
Signal API Token	Gateway auth token (keep secret).	`sgl_live_xxxxxxxxx`

Click Save / Connect. A lightweight validation request is sent (HEAD or small POST depending on gateway adapter) – failures surface immediately.

Testing the Gateway (Optional)

Before wiring Garmingo, verify manually:

curl -X POST \
	-H "Authorization: Bearer <TOKEN>" \
	-H "Content-Type: application/json" \
	https://signal.example.com:8080/send \
	-d '{"number": "+49123456789", "recipients": ["+49111222333"], "message": "Signal test OK"}'

Expect HTTP 200/202. Any 4xx means auth / format issue; 5xx indicates gateway failure.

Event Coverage

Recommended to enable only high‑impact events:

Monitor DOWN / UP (recovery)
Incident created / resolved / severity change
Optional: Maintenance started / ended (only for premium stakeholders)

Message Format

Default layout (first line optimized for quick glance):

[CRITICAL][DOWN] API Gateway – 5xx spike
Region: eu-central-1
Duration: 2m 14s
Link: https://status.example.com/incidents/123

You can fine‑tune which dynamic fields appear (where supported) under Integration → Edit later.

Security

Treat the Signal API Token as a secret (store in a vault; do not commit to code repos).
Use HTTPS only; reject plain HTTP.
Restrict gateway firewall to only Garmingo egress IPs (if your plan exposes them) to reduce abuse surface.
Rotate the token at least every 90 days or immediately upon suspicion of compromise.
Monitor gateway logs for unusual burst patterns.

Rotation Procedure

Create a new token in the gateway.
Update the integration in Garmingo with the new token (keep tab open).
Send a test (incident test or dummy monitor) → confirm delivery.
Revoke the old token.

Troubleshooting

Symptom	Likely Cause	Resolution
401 / Unauthorized	Wrong or expired API Token	Regenerate token; update integration; retest
400 / Validation error	Malformed phone number	Use full E.164 `+<country><number>` format
Timeout / No response	Gateway offline / DNS failure	Check container / service logs; verify DNS & TLS cert
Delivered twice	Gateway retry logic + slow ack	Ensure idempotent handling; tune gateway timeout
Incident not sent but monitor alerts are	Event filtering excludes incident types	Edit integration → enable incident events

Best Practices

Keep Signal reserved for critical, low-volume alerts to maintain signal/noise ratio.
Combine with a broader channel (email / Slack) for verbose context; link back rather than duplicating full payload.
Sanitize dynamic titles (avoid secrets / internal hostnames when possible).

Data Privacy

Only the message text, severity metadata, and link are transmitted. No credentials or raw logs are included. For additional redaction, adjust the incident / monitor templating rules before Signal dispatch.

Signal

On this page