Status Monitoring

What is OpenStatus?

OpenStatus is an open-source monitoring and status page platform. It provides everything Decode Hash needs to track API health, measure response latency, and communicate service status to users.

Getting Started

Follow these steps to get OpenStatus running for Decode Hash:

• 1Sign up at openstatus.dev using your GitHub or email account.
• 2Create a workspace named decode-hash. This workspace groups all your monitors, status pages, and incidents.
• 3Invite your team so that all relevant engineers have access to manage monitors and respond to incidents.

Setting Up Your Status Page

The status page is the public-facing dashboard where users can check whether Decode Hash is operational. Configure it to match the Decode Hash brand.

1. Create the status page

In your OpenStatus dashboard, go to Status Pages and click Create Status Page. Set the slug to decode-hash so your default URL becomes decode-hash.openstatus.dev.

2. Configure custom domain

Under Settings → Custom Domain, enter status.decode.cowdi.co. Then add a CNAME record in your DNS provider:

Type:  CNAME
Name:  status
Value: cname.openstatus.dev

DNS propagation typically takes a few minutes. OpenStatus will automatically provision an SSL certificate for the custom domain.

3. Customize branding

Upload the Decode Hash logo and configure the status page colors to match the Decode Hash brand:

Configuring Monitors

Monitors check your endpoints at regular intervals from multiple regions. Set up the following monitors for comprehensive coverage.

Monitor 1: API Health Check

A basic availability check that verifies the API is responding. This is the primary uptime indicator.

Monitor 2: Lookup Latency

Tracks the actual lookup endpoint performance. Uses a test hash to measure real end-to-end response times including p95 latency.

Setting up assertions

Assertions define what a “successful” check looks like. If any assertion fails, the monitor triggers an alert. For each monitor, configure:

• Status code assertion: Expect HTTP 200
• Response time assertion: Response must be under 500ms (well above Decode Hash's typical <2ms, but accounts for network latency from monitoring regions)

Choosing monitoring regions

Select regions geographically close to your users. For Decode Hash (targeting East Africa), use Johannesburg (closest to Kenya), Amsterdam, and Frankfurt (European backbone). This gives you latency data from both near and far locations to detect region-specific issues.

Incident Management

OpenStatus provides a full incident lifecycle from detection through resolution.

Automatic detection

When a monitor fails its assertions (e.g., the health check returns a 500 or times out), OpenStatus automatically detects the issue. By default it waits for multiple consecutive failures before triggering to avoid false positives from transient network issues.

Creating incidents manually

For planned maintenance or known issues that monitors might not catch, create incidents manually from the dashboard. Go to Incidents → Create Incident and provide a title, description, affected monitors, and initial status.

Incident lifecycle

Each incident goes through these statuses:

Subscriber notifications

Users can subscribe to your status page via email. They receive notifications whenever an incident is created, updated, or resolved. This is configured automatically on the status page — subscribers see a “Subscribe to updates” button.

Integrating with Your App

React Status Widget

OpenStatus provides a React component that displays live status in your app. Install the package and add it to your footer or navigation:

npm install @openstatus/react

import { StatusWidget } from '@openstatus/react';

export function Footer() {
  return (
    <footer>
      {/* Other footer content */}
      <StatusWidget slug="decode-hash" />
    </footer>
  );
}

The widget shows a small indicator (green for operational, yellow for degraded, red for down) that links to your full status page.

Status Badge

Embed a status badge in your README, documentation, or any webpage. The badge updates automatically based on your monitor status:

![Decode Hash Status](https://decode-hash.openstatus.dev/badge)

[![Status](https://decode-hash.openstatus.dev/badge)](https://status.decode.cowdi.co)

Monitoring as Code

Define your monitors in a openstatus.yaml file at the root of your repository. This lets you version-control your monitoring configuration alongside your application code:

version: "1"

monitors:
  - url: "https://api.decode.cowdi.co/health"
    name: "API Health"
    method: "GET"
    periodicity: "1m"
    regions:
      - "ams"
      - "fra"
      - "jnb"
    assertions:
      - type: "status"
        target: 200
      - type: "latency"
        target: 500

  - url: "https://api.decode.cowdi.co/v1/lookup"
    name: "Lookup Latency"
    method: "POST"
    periodicity: "5m"
    headers:
      X-API-Key: "${OPENSTATUS_MONITOR_API_KEY}"
    body: '{"hash": "test_hash_value"}'
    regions:
      - "ams"
      - "fra"
      - "jnb"
    assertions:
      - type: "status"
        target: 200
      - type: "latency"
        target: 500

pages:
  - name: "Decode Hash Status"
    slug: "decode-hash"
    custom_domain: "status.decode.cowdi.co"
    monitors:
      - "API Health"
      - "Lookup Latency"

Notifications Setup

Configure alerts so your team knows immediately when something goes wrong. OpenStatus supports multiple notification channels.

CI/CD Integration

Verify that your deployment is healthy by running a health check after each deploy. This catches issues that only appear in production.

GitHub Actions workflow

Add a post-deployment verification step that checks the health endpoint after Railway deploys your app:

name: Post-Deploy Verification

on:
  deployment_status:
    types: [success]

jobs:
  verify:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Wait for deployment to stabilize
        run: sleep 30

      - name: Check API health
        run: |
          STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
            https://api.decode.cowdi.co/health)
          if [ "$STATUS" != "200" ]; then
            echo "Health check failed with status $STATUS"
            exit 1
          fi
          echo "Health check passed"

      - name: Check lookup endpoint
        run: |
          RESPONSE=$(curl -s -w "\n%{http_code}" \
            -X POST https://api.decode.cowdi.co/v1/lookup \
            -H "Content-Type: application/json" \
            -H "X-API-Key: ${{ secrets.DECODE_HASH_MONITOR_KEY }}" \
            -d '{"hash": "test_hash_value"}')
          STATUS=$(echo "$RESPONSE" | tail -1)
          if [ "$STATUS" != "200" ]; then
            echo "Lookup check failed with status $STATUS"
            exit 1
          fi
          echo "Lookup check passed"

      - name: Notify on failure
        if: failure()
        run: |
          curl -X POST ${{ secrets.SLACK_WEBHOOK_URL }} \
            -H "Content-Type: application/json" \
            -d '{"text": "Post-deploy verification failed for Decode Hash API"}'