Troubleshooting

Two tools answer most questions: getStats() in your app, and the SDK's debug output (debug: true for SDK problems, debug: 'inbound' for webhooks).

import { getStats } from '@theirside/sdk';

const stats = getStats();
if (!stats) console.log('the SDK is off: no apiKey or endpoint, or enabled: false');
else console.log(stats.sent, stats.queued, stats.dropped, stats.lastFlushError);

A provider doesn't show up

1. Is the SDK on? getStats() returns undefined when apiKey or endpoint is missing: check THEIRSIDE_API_KEY and THEIRSIDE_COLLECTOR_URL reach the process.
2. Does it send? sent should grow after the app has made a few calls, and lastFlushError stay undefined. If not, see The collector is unreachable.
3. Is init() early enough? In ES modules it must run in a file imported before the rest of your app (Node servers).
4. Is the host your own? Loopback, private networks, internal names (*.internal, *.svc, single-label hosts) and telemetry endpoints are never recorded. A partner API on a private address needs providers: [{ name, hosts }].
5. Hidden? Check Settings → Providers for a hidden provider or host.
6. Right project and environment? The API key decides the project; the environment picker at the top of the dashboard filters by environment.

Turn on debug: true to see bad options, flush failures and template overflows in your app's console. Settings → SDK health shows each service and process the collector has heard from.

A webhook isn't discovered

1. Start the receiving service with THEIRSIDE_DEBUG=inbound (or debug: 'inbound') and send one delivery. The line for it says what happened: recorded as a delivery from …, candidate …, or ignored, … with the reason.
2. No line at all? The request didn't reach a process with the SDK, or init() ran after the server was created. On AWS Lambda the handler must be wrapped with wrap() (Serverless); other function platforms and Workers don't record incoming requests.
3. ignored, no webhook signal: the request has no route word, signature header, CloudEvents headers or webhook host. Declare the route: webhooks: [{ path, provider }] (Webhooks).
4. ignored, browser or front-end request: it carries cookies or Origin; real webhooks don't.
5. Recorded, but not in the dashboard? The flush line says whether it was sent (… to /v1/ingest: 202), held (waiting for the collector to confirm it stores webhooks) or not sent: timeout. On Lambda, add inbound: true. getStats().inbound shows held, sent and dropped.
6. Ignored in the dashboard earlier? Restore it under Settings → Providers → Discovered webhook routes.

Alerts are too noisy

• The first day: each endpoint learns its normal for 24 hours and uses cautious defaults meanwhile. Webhook silence alerts need three weeks of history.
• An error status that is a normal answer (a 400 for "no consent yet"): mark it as expected, in code or from the incident (Expected outcomes).
• A provider you don't need alerts for: turn its alerts off on its page or in Settings → Providers; it stays monitored on the dashboard.
• Too sensitive in general, or for one provider: Settings → Thresholds, or the provider's settings, adjust the thresholds.
• Test or staging traffic mixed in: give it its own environment so it learns separately.

The collector is unreachable

Your app is never affected: the SDK keeps events in memory up to maxQueue (10,000), drops the oldest beyond that and counts them, and retries with backoff. getStats().lastFlushError says why sending fails:

On the collector side: GET /readyz answers 200 when it is ready and 503 while its database is unreachable; its log says why.