Events
Section titled “Events”| Event | When |
|---|---|
new_blocking |
a full-detail result is uploaded and an error-level, gate-counting finding appears that was not active in the previous observation of that workspace. A first upload announces all of them. An upload with incomplete coverage, a Deep or known-fix error, or findings without fingerprints announces nothing, and a changed rule or engine profile resets the comparison without announcing |
assignment |
an administrator’s review assigns a finding to a different owner |
expiring_risk |
an accepted risk in an uploaded release decision expires within 7 days |
failed_scheduled_scan |
a scheduled Cloud scan fails (not when cancelled); needs the scan scheduler, which is not live |
Each event is sent once per recipient and destination: a repeated event with the same key is not queued again.
Preferences API
Section titled “Preferences API”| Method and path | Needs | Does |
|---|---|---|
GET /api/v1/notifications/preferences |
a person’s credential with scans:read |
your preferences. Default {enabled: false, events: [], destinations: []} |
PUT /api/v1/notifications/preferences |
a person, with a fresh step-up proof | sets {enabled, events, destinations}: at most 4 events and 10 destinations. Errors: invalid_notification_preferences, notification_destination_required (enabled without events or destinations), person_required (an API key or worker token) |
POST /api/v1/notifications/drain |
an administrator, with step-up | delivers at most one queued message per call and runs the expiring-risk sweep. Answers {delivered: 0, disabled: true} when no transport is configured |
Destinations are not addresses: they are ids of destinations that the Cloud operator configured for your organization and for you. Preferences never hold a URL, an email address or a secret. There is no settings page yet; the API is the only way. The routes are in the Cloud API reference.
Channels
Section titled “Channels”| Channel | Sent to | Body |
|---|---|---|
| Slack | chat.postMessage, a channel id (C…, G…, D…) |
plain text, no unfurling |
| through Resend | subject and plain text | |
| Webhook | an HTTPS URL on an operator allowlist | JSON {schema: "keryn.dev/notification/v1", idempotencyKey, title, text, url, sourceIncluded: false}, with the operator’s Authorization: Bearer secret; no HMAC signature |
Every request carries an idempotency-key, follows no redirect and sends no cookies.
What a message contains
Section titled “What a message contains”A message has a fixed title, for example New blocking finding requires review. Its text is always Sign in to review the recorded event. Source code, finding prose and credentials are excluded. It also carries a link to the Keryn Cloud API record (a scan, a result’s reviews, or your account), which needs your normal sign-in and organization access to open.
It never contains source code, a finding’s message or evidence, rule text, the repository name or any credential.
Delivery
Section titled “Delivery”- Queueing. One row per recipient and destination; a repeated event is dropped as a duplicate.
- Leases. A delivery holds a 60-second lease. A lease that expires mid-send marks the message uncertain, and it is never sent again. Keryn deliberately does not claim exactly-once delivery.
- Checks before sending. Membership, preferences, the destination binding, and that the result and event still exist and are current. A member whose access is limited to some projects is never notified. A failed check cancels the message.
- Retries. Rate limiting (HTTP 429, or Slack
ratelimited) is retried after 30 s with the same idempotency key, up to 5 attempts; then the message is failed. - Other outcomes. Any other error or a timeout (10 s) is uncertain.
- States:
queued,delivering,delivered,uncertain,failed,canceled.
Notification data is included in an organization’s export and deletion.
Not live yet
Section titled “Not live yet”- the database migration in production;
- operator-configured destinations, a secret resolver and a delivery transport;
- a scheduler that runs scans with a schedule and drains the queue (today an administrator’s call delivers one message);
- a settings page;
- the owner’s go-ahead for real messages.