Handling alerts

Pull, push, deduplication, and reconciliation

You have three ways to receive alerts, in increasing operational complexity:

1. Polling. A scheduled job calls GET /v1/alerts and walks pages until it sees an id you’ve already stored.
2. Webhook. Register an endpoint via POST /v1/webhooks and let Signa push alerts to you.
3. Webhook + reconciliation. Push for low latency, then periodically call POST /v1/alerts/lookup with the IDs you’ve persisted to confirm nothing was lost during a receiver outage.

Pure polling is fine for low-volume internal tools. For production external workflows, prefer webhook + reconciliation.

Deduplicate by alert ID

Alerts are immutable, but the same alert.created event can arrive at your endpoint multiple times across retries and redeliveries. Use the webhook-id header (which equals the alert’s prefixed ID, alt_*) as your idempotency key.

const alertId = req.header('webhook-id')!;
if (await alreadyProcessed(alertId)) {
  return res.sendStatus(200); // ack but skip
}
// Record processing and execute the side effect in the same transaction
// so a crash between them leaves the alert unprocessed (and retriable),
// not silently "done".
await db.transaction(async (tx) => {
  await markProcessed(tx, alertId);
  await handle(tx, JSON.parse(req.body));
});
return res.sendStatus(200);

If your side effect cannot share a transaction with your dedup store (for example, a third-party API call), use a two-stage processing -> done state and only flip to done after the side effect returns success.

Polling pattern

let cursor: string | undefined;
while (true) {
  const page = await signa.alerts.list({ limit: 100, cursor });
  for (const alert of page.data) {
    if (await alreadyProcessed(alert.id)) {
      // Caught up, older alerts have already been processed.
      return;
    }
    await markProcessed(alert.id);
    await handle(alert);
  }
  if (!page.has_more) return;
  cursor = page.pagination.cursor!;
}

The GET /v1/alerts endpoint accepts:

Parameter	Type	Notes
limit	number	1-100, default 20.
cursor	string	Opaque cursor from the previous response.
severity	normal | high | critical	Filter by severity.
event_type	string	One of the five alert event types: trademark.created, trademark.updated, trademark.status_changed, trademark.retracted, trademark.corrected.
epoch	all | current	all (default) returns alerts across every version of the watch’s query. Set to current to keep only alerts matching the watch’s present query.

Reconciliation pattern

For defense-in-depth on top of webhooks, run a periodic job that asks Signa “did you ever fire these IDs?”, useful when you suspect a webhook outage.

const recentIds = await myStore.alertsLast48h();
const confirmed = await signa.alerts.lookup(recentIds);
const seen = new Set(confirmed.map((a) => a.id));
for (const id of recentIds) {
  if (!seen.has(id)) reportPossibleLoss(id);
}

alerts.lookup() takes an array of 1-100 prefixed alert IDs (alt_*) per call:

const alerts = await signa.alerts.lookup([
  'alt_8kLm2nPq',
  'alt_9pQs3vNk',
  'alt_7hRt4xQw',
]);
// alerts is an array of Alert objects, unknown or cross-org IDs are
// silently omitted, so alerts.length <= ids.length

The endpoint is organization-scoped. Malformed IDs, anything that is not a well-formed alt_* ID, fail the whole request with 400 validation_error, listing each bad entry by index. Well-formed but unknown IDs, and IDs that belong to another organization, are silently dropped from the result. Any gap between the IDs you sent and the alerts you got back is real.

Severity-based routing

A typical production setup runs two jobs on different cadences:

Cadence	Filter	What it does
Every minute	severity=critical	Pages on-call.
Hourly	(no filter)	Catches normal and high for the daily review queue.

const critical = await signa.alerts.list({ severity: 'critical' });
for await (const a of critical) routeToOnCallAttorney(a);

Provenance: every alert’s evidence chain

Each alert carries a provenance block so you can trace it from the office publication to the moment Signa detected it, and see whether that detection was on time.

"provenance": {
  "sync_run": "srun_01HK...",
  "content_version": 7,
  "detection_latency_seconds": 9840,
  "late_detection": false
}

Field	Meaning
sync_run	The ingestion run that detected this change, as a prefixed srun_ ID. Cross-references last_relevant_sync_run.sync_run on the watch diagnostics endpoint. Omitted (not null) when the alert predates provenance tracking and has no derivable run.
content_version	The record version the alert froze against. Same value used for alert deduplication.
detection_latency_seconds	created_at - occurred_at: the gap between when the office published the change (timestamps.occurred_at) and when Signa detected it (timestamps.created_at). null when the source did not publish a timestamp we could anchor to, or published a timestamp later than our detection time.
late_detection	true when detection_latency_seconds exceeded Signa’s internal service-level target for that office. It is always false when the latency is unknown: Signa never flags lateness it cannot prove.

late_detection is a per-office judgement. Offices that publish daily have a tight target; offices that publish weekly or monthly have a proportionally looser one. A false flag means “detected within the window we hold ourselves to for that office”, not “instant”.

Use detection_latency_seconds for your own SLA dashboards, and late_detection as a ready-made trigger for exception review when Signa was slower than intended.