Troubleshooting

Use the diagnostics endpoint to find out why an alert didn’t fire, and monitor Signa’s own uptime

When an expected alert doesn’t arrive, the diagnostics endpoint tells you exactly why, so you can separate query, delivery, and platform issues quickly.

Step 1: Run the diagnostics

For each (watch, trademark) pair you expected an alert for, call GET /v1/watches/{id}/diagnostics:

const trace = await signa.watches.diagnostics('wat_01HK7M...', {
  trademarkId: 'tm_01HK7N...',
});
console.log(trace.reason);

The reason field gives you the answer in plain English. The endpoint walks the evaluation steps in order and surfaces the first failure.

Step 2: Interpret reason

reason value	Meaning	Next step
alert fired	Alert was generated. Use alert_id to chase webhook delivery.	See Step 3.
watch does not include office {code}	The watch’s filters.offices (or filters.jurisdictions) doesn’t include this trademark’s office.	PATCH the watch to add the office. The widened criteria apply automatically to future data updates.
trademark evaluated more than 90 days ago; provenance no longer available	Outside the 90-day diagnostic horizon.	The trace cannot be regenerated. Check the diagnostics data_window object for every retention horizon, and diagnose future misses within it. If the mark still matches the watch, it will be re-evaluated on the next update going forward.
trademark not in candidacy window for the most recent {office} sync run	Signa hasn’t seen a change to this trademark from that office since the watch last checked it.	Run POST /v1/watches/preview with the watch’s query to confirm the trademark would match today.
trigger event {type} not in watch.trigger_events	The watch’s trigger_events filter excluded this event type. For example, you watch only trademark.created but this was a trademark.updated.	Widen trigger_events via PATCH. The new shape applies to future updates automatically.
no matching reason available	Fallback.	File a support ticket with the request_id. This should not happen in steady state.

Step 3: Cross-reference webhook delivery

When alert_fired=true but you never saw it on your receiver, follow the trace to the delivery log:

// 1. The alert fired. alert_id (alt_*) is the cross-system trace handle.
const trace = await signa.watches.diagnostics('wat_01HK7M...', { trademarkId });
console.log(trace.alert_id);

// 2. List delivery attempts for the endpoint subscribed to alert.created.
const deliveries = await signa.webhooks.listDeliveries('whk_01HK...', {
  since: '2026-05-01T00:00:00Z',
});

// 3. Find the delivery rows for that alert and inspect the outcome.
for await (const d of deliveries) {
  if (d.alert_id === trace.alert_id) {
    console.log(d.status, d.http_status, d.error_reason, d.response_body);
  }
}

Likely outcomes:

• delivered: receiver returned 2xx but may not have stored it. Inspect response_body and your own logs.
• failed: non-2xx response. error_reason (e.g. non_2xx_500) and http_status tell you which side broke. Up to 7 attempts total.
• exhausted: all attempts failed. Replay manually with POST /v1/webhooks/{id}/deliveries/{did}/redeliver.
• pending: still queued. Wait, or check /health/ready to confirm Signa is up.

If the endpoint was auto-disabled mid-flight, check GET /v1/webhooks/{id}. status='disabled' plus disabled_reason (auto_consecutive_100, auto_failure_rate_50_over_50, or manual) explains why. Re-enable with PATCH /v1/webhooks/{id} once the receiver is healthy again.

Step 4: Confirm Signa is healthy

Before assuming a Signa-side bug, check readiness (see Monitor Signa uptime below). Retry the diagnostic flow once the platform reports ok.

Monitor Signa uptime

Two unauthenticated health endpoints let you monitor Signa from your own observability stack, useful for SLA reporting, status-page integration, and incident triage.

Endpoint	What it tells you
GET /v1/health	The API process is up. Always returns HTTP 200 and {"status":"ok"}; it does not check dependencies, so it cannot report degraded or unhealthy.
GET /health/ready	The API plus its database, cache, and search dependencies are reachable. Returns status: "ok", "degraded" (a non-critical dependency is down, most requests still work), or "unhealthy" (503; a critical dependency is down).

Use /health/ready for real uptime and incident-detection monitoring; use /v1/health only as a lightweight liveness ping. Both endpoints are unauthenticated, no API key is required for your monitoring agent.

curl https://api.signa.so/health/ready

{
  "status": "ok",
  "service": "core-api",
  "uptime_ms": 1234567,
  "dependencies": {
    "postgres": { "status": "ok", "latency_ms": 4 },
    "valkey": { "status": "ok", "latency_ms": 1 },
    "opensearch": { "status": "ok", "latency_ms": 6 }
  }
}

Example synthetic check, adjust to your monitoring tool of choice. Assert only on the HTTP status code (200 vs 503), that already separates “up” (ok or degraded) from “down” (unhealthy); asserting the body’s status equals exactly "ok" would page you on every non-critical dependency blip:

type: api
name: Signa API readiness
config:
  request:
    method: GET
    url: https://api.signa.so/health/ready
  assertions:
    - type: statusCode
      operator: is
      target: 200
options:
  tick_every: 60

If you want visibility into degraded without paging on it, log the response body’s status field separately as a warning-level signal. A cron or uptime-checker version of the same check:

#!/usr/bin/env bash
set -e
RESPONSE=$(curl -fsS --max-time 5 https://api.signa.so/health/ready)
STATUS=$(echo "$RESPONSE" | jq -r '.status')
if [ "$STATUS" = "ok" ] || [ "$STATUS" = "degraded" ]; then
  exit 0
fi
echo "Signa API ${STATUS}: ${RESPONSE}" >&2
exit 1

What /health/ready doesn’t cover

/health/ready is API-side health only. It does not surface:

• Data freshness for a specific office. An office falling behind on updates doesn’t flip the API to degraded. If you watch a specific office and alerts stop firing, check the diagnostics endpoint, last_relevant_sync_run.completed_at will be stale.
• Webhook delivery. That’s between Signa and your receiver. Cross-check GET /v1/webhooks/{id}/deliveries for the delivery audit log.

If /health/ready is green but you suspect a Signa-side issue with a specific watch, use the diagnostics endpoint above.

Signa does not currently publish a public status page. If you maintain your own, surface /health/ready and the diagnostics-derived freshness signal separately, they cover different incident classes. For incident questions, email [e-mail], or report a reproducible platform bug programmatically via POST /v1/feedback (attach the request_id from a failed call so we see exactly what you hit).

Retention

Data	Window
Change records (used for diagnostic lookups)	90 days
Webhook delivery audit	30 days
Alerts	90 days
Diagnostic freshness horizon	90 days

Past the diagnostic horizon, evaluated=false and reason explains the freshness limit. A watch always continues to evaluate new data going forward, the horizon only limits the backward-looking diagnostic trace.