Troubleshooting

Use the diagnostics endpoint to find out why an alert didn’t fire

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 outbox_event_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, then optionally replay so the widened watch re-evaluates from the next ingestion sync forward.
trademark evaluated more than 90 days ago; provenance no longer available	Outside the 90-day diagnostic horizon.	The trace cannot be regenerated — replay is forward-only in beta (from_date is rejected with 400). If the mark still matches, replay re-evaluates it on the next sync going forward. Check the diagnostics data_window object for every retention horizon, and diagnose future misses within it.
trademark not in candidacy window for sync_run {id}	No change record was emitted. The trademark hasn’t changed in any way Signa considers material (the {id} is 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_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 and replay if needed.
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. outbox_event_id cross-references your endpoint logs.
const trace = await signa.watches.diagnostics('wat_01HK7M...', { trademarkId });
console.log(trace.outbox_event_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 matching event_id and inspect the outcome.
for await (const d of deliveries) {
  if (d.event_id === trace.outbox_event_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

Data	Window
Change records (used for candidacy 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. The provenance is gone at that point; replay re-evaluates from the next ingestion sync forward only (historical replay from a chosen date is reserved for v1.1), so diagnose suspected misses while they’re inside the window.