Monitoring Matrix Synapse with Vigilmon: Client API, Federation, TCP Port 8448 & SSL Alerts

Matrix Synapse is the reference homeserver implementation for the Matrix open standard — a decentralized, end-to-end encrypted messaging protocol used by organizations that need full control over their communications infrastructure. Teams run Synapse to power internal chat, replace Slack or Teams with a self-hosted alternative, and federate with the broader Matrix network. Synapse is more than a chat server: it bridges rooms, handles VoIP signaling, manages end-to-end encryption keys, and federates messages with other homeservers in real time. When Synapse goes down, those conversations stop — clients disconnect, messages queue up, and federation with other homeservers breaks. Vigilmon gives you external visibility into Synapse's client API, federation endpoint, TCP port, and SSL certificate so you're alerted before your team's messages stop flowing.

What You'll Build

• A monitor on Synapse's /_matrix/client/versions well-known endpoint
• A liveness check on the federation API (/_matrix/federation/v1/version)
• A TCP monitor for the federation port (8448)
• SSL certificate monitoring for your Synapse domain

Prerequisites

• A running Matrix Synapse homeserver with a public domain (e.g., matrix.example.com)
• HTTPS configured — Matrix requires TLS for both client and federation traffic
• Port 8448 accessible for federation traffic (or 443 with delegation)
• A free account at vigilmon.online

Step 1: Verify the Client API Well-Known Endpoint

Matrix clients discover your homeserver's capabilities via the /_matrix/client/versions endpoint. This unauthenticated endpoint returns the list of Matrix client-server API versions your homeserver supports:

curl https://matrix.example.com/_matrix/client/versions

A healthy Synapse instance returns HTTP 200 with a JSON body like:

{
  "versions": ["r0.0.1","r0.1.0","r0.2.0","r0.3.0","r0.4.0","r0.5.0","r0.6.1","v1.1","v1.2","v1.3","v1.4","v1.5"]
}

This endpoint requires no authentication and is guaranteed to be present on any Matrix-compliant homeserver. Clients use it to negotiate API compatibility — if it's unreachable, Matrix clients can't connect to your homeserver at all.

Step 2: Create a Vigilmon HTTP Monitor for the Client API

1. Log in to Vigilmon → Add Monitor → HTTP.
2. URL: https://matrix.example.com/_matrix/client/versions.
3. Check interval: 60 seconds.
4. Response timeout: 10 seconds.
5. Expected status: 200.
6. Keyword: versions.
7. Label: Synapse Client API.
8. Click Save.

This monitor catches:

• Synapse process crashes or unexpected restarts
• Database connectivity failures — Synapse requires PostgreSQL (or SQLite for small deployments) to function
• Configuration errors after upgrades that prevent Synapse from starting
• Reverse proxy failures that block client traffic from reaching the homeserver

When this monitor fires, every Matrix client connected to your homeserver loses connectivity — messages stop sending and receiving, and new clients can't register or log in.

Step 3: Monitor the Federation API

Federation is what makes Matrix decentralized — it allows your homeserver to exchange messages with users on other Matrix homeservers in real time. The federation API is served at /_matrix/federation/v1/version and returns information about your homeserver's implementation:

curl https://matrix.example.com/_matrix/federation/v1/version

A healthy Synapse federation endpoint returns HTTP 200 with:

{
  "server": {
    "name": "Synapse",
    "version": "1.95.1"
  }
}

1. Add Monitor → HTTP.
2. URL: https://matrix.example.com/_matrix/federation/v1/version.
3. Check interval: 5 minutes.
4. Expected status: 200.
5. Keyword: Synapse.
6. Label: Synapse Federation API.
7. Click Save.

When the federation monitor fires but the client API monitor stays green, your homeserver can serve local clients but has stopped federating with the broader Matrix network — cross-server room memberships go stale and messages to users on other homeservers queue up.

Note: If your Synapse federation port uses a non-standard setup (e.g., delegation via .well-known/matrix/server pointing to a different port), update the URL to match your federation delegation target.

Step 4: Create a TCP Monitor for the Federation Port

Matrix federation traffic runs on port 8448 by default. A TCP check on this port confirms Synapse's federation listener is bound and accepting connections at the network layer, independently of the HTTP response:

1. Add Monitor → TCP.
2. Host: matrix.example.com.
3. Port: 8448.
4. Check interval: 60 seconds.
5. Response timeout: 10 seconds.
6. Label: Synapse Federation TCP 8448.
7. Click Save.

Delegation note: Many Synapse deployments use port delegation to run federation on port 443 rather than 8448. If you've configured delegation (via /.well-known/matrix/server or DNS SRV records pointing to port 443), the federation HTTP monitor in Step 3 covers this. Set the TCP monitor to port 443 and label it accordingly, or skip the TCP monitor if port 443 is already covered by your client API HTTP monitor.

When the TCP monitor fires but the federation HTTP monitor is also failing, Synapse's federation listener has stopped — the process may have crashed or the port configuration changed. When only the TCP monitor fires, a firewall or routing change has blocked port 8448 without affecting Synapse itself.

Step 5: Monitor SSL Certificates

Matrix requires TLS for both client-server and server-server (federation) traffic. An expired SSL certificate has severe consequences for a Matrix homeserver:

• All Matrix clients disconnect immediately — Element, FluffyChat, and other clients refuse connections with expired certificates
• Federation with other homeservers breaks — other Matrix servers reject connections to your homeserver
• End-to-end encryption key exchange stops, which may cause key verification errors even after the certificate is renewed
• Any bridges (IRC, Slack, Discord) that connect through your homeserver lose their connections

1. Add Monitor → SSL Certificate.
2. Domain: matrix.example.com.
3. Alert when expiry is within: 30 days.
4. Alert again: 14 days, 7 days, 3 days, 1 day.
5. Click Save.

Certificate scope: If your Synapse deployment uses separate certificates for the client API (port 443) and federation (port 8448), create separate SSL monitors for each domain/port combination. Federation certificate expiry may not affect the client-facing certificate.

Step 6: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Action | |---|---|---| | Client API (/_matrix/client/versions) | Non-200 or versions missing | Check Synapse process; inspect PostgreSQL connectivity; review Synapse logs | | Federation API | Non-200 or keyword missing | Check federation listener config; verify port 8448 routing; inspect reverse proxy | | TCP Port 8448 | Connection refused or timeout | Check Synapse federation listener; verify firewall allows port 8448 inbound | | SSL certificate | < 30 days to expiry | Renew certificate; check ACME/Let's Encrypt for matrix.example.com |

Alert after: 2 consecutive failures for HTTP monitors. 1 failure for the TCP monitor — a stopped federation listener won't restart on its own.

Common Matrix Synapse Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Synapse process crash | Client API and TCP monitors fire; alert within 60 s | | PostgreSQL connection failure | Synapse unable to serve requests; client API monitor fires | | Database migration failure after upgrade | Synapse exits on startup; all monitors fire | | Federation port blocked by firewall | TCP 8448 monitor fires; client API may stay green | | Federation listener misconfigured | Federation API monitor fires; client API stays green | | Media repository storage full | Synapse may degrade; media uploads fail silently | | Out-of-memory kill on large homeservers | Synapse OOM-killed; all monitors fire simultaneously | | SSL certificate expires | SSL monitor alerts at 30 days; all clients disconnect, federation breaks | | Synapse worker crash (if using workers) | Specific API paths fail; /versions may still respond | | DNS misconfiguration | All monitors fire simultaneously; federation breaks globally |

Matrix Synapse carries your team's real-time communications and in many deployments is the backbone of incident response coordination — the place engineers coordinate when things are on fire. Vigilmon watches the client API, federation endpoint, TCP port, and SSL certificate so you're alerted within 60 seconds of any failure, giving you time to restore your homeserver before your team needs it most.

Start monitoring Matrix Synapse in under 5 minutes — register free at vigilmon.online.