Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Notifications

    Describes Keryn 0.5.2 and keryn-rules 0.8.0. Changelog

    View as Markdown
    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.

    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.

    Channel Sent to Body
    Slack chat.postMessage, a channel id (C…, G…, D…) plain text, no unfurling
    Email 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.

    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.

    • 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.

    • 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.