Skip to main content
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 valueMeaningNext step
alert firedAlert 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 to future ingestion going forward — the watch re-evaluates with its new shape on the next sync automatically.
trademark evaluated more than 90 days ago; provenance no longer availableOutside 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 sync going forward.
trademark not in candidacy window for the most recent {office} sync runNo change record was emitted. The trademark hasn’t changed in any way Signa considers material during the most recent ingestion cycle for this office since the watch was created.Run POST /v1/watches/preview with the watch’s query to confirm the trademark would match today.
trigger event {type} not in watch.trigger_eventsThe 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 ingestion automatically.
no matching reason availableFallback.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 retries.
  • exhausted — all retries failed. Replay manually with POST /v1/webhooks/{id}/deliveries/{did}/redeliver.
  • pending — still queued. Wait or check /v1/health 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, hit /v1/health. It returns instantly without auth and surfaces degraded readiness if a dependency is impaired. 
curl https://api.signa.so/v1/health
If the platform is degraded the status will be degraded or unhealthy. Retry the diagnostic flow once the page clears.

​
Retention

DataWindow
Change records (used for candidacy lookups)90 days
Webhook delivery audit30 days
Alerts90 days
Diagnostic freshness horizon90 days
Past the diagnostic horizon, evaluated=false and reason explains the freshness limit. The provenance is gone at that point, so diagnose suspected misses while they’re inside the window. A watch always continues to evaluate new ingestion going forward — the horizon only limits the backward-looking diagnostic trace.