How to Monitor Port (port.io) Developer Portals with Vigilmon

Port is an internal developer portal platform that centralizes service catalogs, scorecards, self-service actions, and software templates into a single developer-facing hub. When Port is unavailable or degraded, engineers lose access to the service catalog, can't trigger self-service workflows, and onboarding grinds to a halt.

This tutorial shows you how to monitor Port's API, webhooks, and your own Port instance with Vigilmon — free tier, no credit card required.

Why monitoring your developer portal matters

Developer portals sit in the critical path of engineering productivity. A silent outage has compounding effects:

• Service catalog inaccessible — engineers can't look up ownership, dependencies, or runbooks during an incident
• Self-service actions blocked — scaffolding new services, provisioning environments, or rotating secrets all fail silently
• Webhook delivery failures — Port ingests data from CI/CD, GitHub, and cloud providers via webhooks; if your endpoint is down, your catalog goes stale
• Scorecard data gaps — reliability and security scorecards stop updating, creating false "green" readings in your engineering metrics

Port does publish a status page, but you need your own monitoring to catch issues in your custom integrations, webhook receivers, and Port-to-internal-tool pipelines.

What you'll need

• A Port account and your organization's Port instance URL
• Your Port API credentials (Client ID and Client Secret from the Port Builder settings)
• A free Vigilmon account

Step 1: Identify what to monitor

Port exposes several components worth watching independently:

| Component | What to check | |-----------|---------------| | Port API (api.getport.io) | Availability of catalog queries and actions | | Your webhook receiver | Endpoint Port POSTs blueprint and entity events to | | Port portal URL | The web UI your engineers use daily | | Self-service action backend | Internal endpoints triggered by Port actions |

Step 2: Monitor the Port API endpoint

Port's API is the backbone of every catalog query and action trigger. Add an HTTP monitor to detect outages before your engineers notice:

1. Log in to vigilmon.online and go to Monitors → New Monitor
2. Choose HTTP / HTTPS
3. Set the URL to https://api.getport.io/v1/blueprints
4. Add an Authorization header with a valid Port API token:

Authorization: Bearer <your_port_access_token>

To obtain a token programmatically (useful for a keep-alive heartbeat):

curl -s -X POST https://api.getport.io/v1/auth/access_token \
  -H "Content-Type: application/json" \
  -d '{"clientId":"<CLIENT_ID>","clientSecret":"<CLIENT_SECRET>"}' \
  | jq -r '.accessToken'

5. Set the expected status code to 200
6. Set the check interval to 1 minute
7. Save the monitor

This monitor fires whenever the Port API is unreachable or returning errors — catching both Port-side incidents and networking issues between your VPC and Port's endpoints.

Step 3: Monitor your webhook receiver

Port sends entity and blueprint change events to your registered webhook endpoints. If your receiver is down, your catalog data falls behind without any alert. Set up a TCP or HTTP monitor for your receiver:

1. Go to Monitors → New Monitor
2. Choose HTTP / HTTPS
3. Set the URL to your webhook receiver endpoint, e.g. https://your-internal-tool.example.com/port-webhook
4. Use a HEAD or GET request (configure a lightweight health path if your receiver supports it)
5. Expected status code: 200 or 405 (Method Not Allowed is fine — it means the server is up and listening)
6. Save the monitor

If your webhook receiver is an internal service, expose a /health endpoint alongside the webhook path:

// Express.js example
app.get('/health', (req, res) => res.json({ status: 'ok' }));
app.post('/port-webhook', verifyPortSignature, handlePortEvent);

Step 4: Monitor self-service action backends

Port self-service actions invoke backends — Lambda functions, internal APIs, GitHub Actions, or custom runners. These backends deserve their own monitors:

1. For each action backend, add an HTTP monitor pointing to its health endpoint
2. For Lambda-backed actions, monitor the API Gateway URL:

   https://<api-id>.execute-api.<region>.amazonaws.com/prod/health
   

3. Set alert thresholds to 1 consecutive failure for action backends — users expect self-service actions to work immediately

Step 5: Set up a heartbeat monitor for Port sync jobs

If you run a scheduled job that syncs data into Port (e.g., syncing GitHub repos, AWS resources, or JIRA issues), set up a heartbeat monitor so you know when it stops running:

1. Go to Monitors → New Monitor → Heartbeat
2. Name it something like "Port GitHub sync job"
3. Set the expected interval (e.g., every 60 minutes)
4. Copy the heartbeat ping URL

Add the ping to the end of your sync script:

#!/bin/bash
# sync_to_port.sh

# ... your sync logic ...

# Ping Vigilmon when done
curl -fsS "$VIGILMON_HEARTBEAT_URL" > /dev/null

If the cron job fails or the sync script crashes before reaching the ping, Vigilmon alerts you within one missed interval.

Step 6: Configure alerts

For a developer portal, alert fatigue is real — but missed alerts on the catalog API or action backends directly impact engineering productivity.

Recommended alert channels:

• Slack — post to #platform-alerts for the API monitor and #engineering for the portal UI
• PagerDuty or on-call — only for the Port API if your catalog is business-critical
• Email — appropriate for webhook receiver and heartbeat monitors

Recommended thresholds:

| Monitor | Alert after | |---------|-------------| | Port API | 1 failure (immediate) | | Webhook receiver | 2 consecutive failures | | Self-service backend | 1 failure | | Heartbeat / sync job | 1 missed interval | | Portal UI | 2 consecutive failures |

To add a Slack alert in Vigilmon:

1. Go to Alert Channels → Add Channel → Slack
2. Paste your Slack webhook URL
3. Assign the channel to your Port monitors

Step 7: Create a status page for platform teams

If your developer portal team supports internal customers (other engineering teams), a status page gives them visibility without flooding your Slack channel:

1. Go to Status Pages → New Status Page in Vigilmon
2. Add your Port API monitor, webhook receiver monitor, and action backend monitors
3. Name it "Developer Portal Status" and publish it
4. Share the URL in your internal engineering wiki or platform team docs

Key metrics to watch

Beyond uptime, watch these Port-specific signals:

• Webhook delivery lag — Port's webhook history shows delivery times; spikes indicate your receiver is slow under load
• Action execution latency — how long self-service actions take end-to-end
• Entity sync freshness — if synced entities (GitHub repos, cloud resources) show a stale updatedAt, your sync job may be silently failing
• Blueprint schema drift — unexpected 4xx errors from the API often indicate a blueprint schema mismatch after a Port update

What's next

• SSL certificate monitoring — Vigilmon checks TLS certificates and alerts before expiry, important for your webhook receiver and action backends
• Multi-region checks — verify your webhook receiver is reachable from multiple geographic regions, not just your primary cloud region
• Incident history — Vigilmon's incident log gives you MTTD/MTTR data to include in your platform team's reliability reports

Get started free at vigilmon.online — monitors go live in under a minute, no credit card required.