Inbound integrations

Inbound integrations let an external monitoring or alerting tool open work in ScopeKite. Each signed event becomes an ordinary task in one project that an owner or admin chooses when the integration is created — routing is fixed at configuration time and can never be chosen by a payload.

Setting one up

1. Open Workspace Settings → Integrations (owners and admins only; also reachable from the command palette as “Manage integrations”).
2. New integration — give it a name and pick the destination project.
3. Save the signing secret from the creation dialog. It is shown exactly once; ScopeKite stores it only for signature verification and cannot reveal it again. If it is lost, delete the integration and create a new one.
4. Copy the ingest endpoint and use the built-in “Send a signed request” example to configure the sender. Requests are authenticated with the Standard-Webhooks scheme: an HMAC-SHA256 signature over id.timestamp.body in the webhook-signature header, with webhook-id and webhook-timestamp alongside. Timestamps older than five minutes are rejected, and a repeated webhook-id is acknowledged but ignored.
5. Send test event creates one clearly-labelled test task in the destination project through the exact pipeline a real event uses. Repeating the test updates that same task — it never piles up duplicates.

How events become work

• The event body is a small neutral shape — title, optional severity, fingerprint, source, occurredAt, detailsUrl — never a raw vendor payload. Vendor-specific adapters are deliberately later work.
• A repeated fingerprint updates one task (occurrence count and a note in the task’s activity) instead of flooding the project.
• Severity is recorded on the incident, not mapped onto the task’s priority — an external tool’s “critical” is not automatically your team’s.

Health, honestly

The integrations list shows facts, not verdicts: when the last event was accepted, how many events and tasks exist, and how many requests were rejected (bad signature, stale timestamp, invalid payload) and when the last rejection happened. An integration that has never received an event says so — silence is not proof of health.

Deleting

Deleting an integration takes effect immediately: the ingest endpoint stops accepting events and the secret becomes useless. Tasks the integration created are ordinary work and stay exactly where they are.

Decision record: ADR-030.