Handling alerts

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

Polling. A scheduled job calls GET /v1/alerts and walks pages until it sees an id you’ve already stored.
Webhook. Register an endpoint via POST /v1/webhooks and let Signa push alerts to you.
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 event ID

Alerts are immutable, but the same alert.created event can arrive multiple times. Use the stable evt_* value in the webhook-id header as your idempotency key; use data.alert_id for the alert resource.

const eventId = req.header('webhook-id')!;
if (await alreadyProcessed(eventId)) {
  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, eventId);
  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.

Reading `event.diff`

event.diff is why the alert fired, one entry per changed field:

"event": {
  "type": "trademark.status_changed",
  "summary": "Status changed: pending → registered",
  "diff": [
    { "path": "status", "op": "set", "from": "pending", "to": "registered" },
    { "path": "owners", "op": "changed" }
  ]
}

path is a public trademark field name — the same name the field has on GET /v1/trademarks/{id}, so you can always look it up. Changed child collections appear as the collection name (owners, attorneys, classifications, media) and are opaque: op: "changed", no from/to. Parent fields carry real values. Status is flattened — status.primary is status, everything else is status_<key> (status_stage, status_effective_date, …). Fields Signa tracks internally but does not publish are omitted, not renamed, so a diff can be shorter than the underlying change. Branch on path for routing (status to the docket, owners to conflicts review) and read summary for the human line.

Beta break, effective on deploy. path previously carried Signa’s internal column names (status_primary, mark_text_primary, trademark_owners, …). See the changelog for the full rename table. Redeliveries and retries of older alerts are re-emitted with the public names.

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.

Getting started

Core concepts

Build with AI

Data

Monitoring

Working with the API

Use cases

Deduplicate by event ID

Polling pattern

Reconciliation pattern

Reading `event.diff`

Severity-based routing

Provenance: every alert’s evidence chain

​Deduplicate by event ID

​Polling pattern

​Reconciliation pattern

​Reading event.diff

​Severity-based routing

​Provenance: every alert’s evidence chain

Deduplicate by event ID

Polling pattern

Reconciliation pattern

Reading `event.diff`

Severity-based routing

Provenance: every alert’s evidence chain