Notifications API

Lists the organization's notifications that cover the project, of every channel, oldest first (at most 50). status, failing_since, last_success_at and last_failure_at are this project's. A webhook's signing secret is never returned here.

Requires the project capability; a reports-only credential is refused 403 forbidden, because the response includes receiver URLs and recipients.

Creates a notification. channel email sends to recipients (owner, or user_ids of the project's members); channel webhook POSTs, signed, to url, which follows the webhook URL rules (https on a public Internet host, port 443 or 8443, else webhook_url_rejected). conditions lists the screen state changes it fires on; an email notification needs at least one, a webhook needs conditions or event_types. screen_tags limits conditions to screens carrying any of those tags; empty means every screen, or audience says which screens in the rules of a campaign audience. min_severity and severity filter and rate the notices, and active_hours holds or drops them outside its windows.

A condition notifies only after it has lasted hold_minutes (default 10), and a resolved notice follows when it clears after a notice went out. The notification covers this project alone; an organization has at most 50 notifications, not counting the defaults the system makes (notification_limit_reached).

A webhook's signing secret is generated by the server and returned only in this answer and in rotate-secret; store it. An exact retry with the same Idempotency-Key returns this same answer, secret included, for twenty-four hours. Notices start with the first event after notification.created.

Requires the project capability; a reports-only credential is refused 403 forbidden, because the response includes the receiver URL or recipients.

Changes any of description (empty clears it), conditions, screen_tags, audience, min_severity, severity, active_hours (null clears each of these), hold_minutes, recipients (email), url and event_types (webhook), destination and telegram_chat_id (Slack, Teams, PagerDuty and Telegram), enabled and snoozed_until; channel never changes.

A field of the other channel is invalid_request. A new url is checked like create.

Setting enabled true on a disabled notification clears its failure state and starts at the event that records the change; nothing from while it was off is sent, and notices still pending from before the disable are failed with webhook_disabled. snoozed_until sends nothing until that instant (at most 30 days ahead; null ends the snooze); notices that fall due meanwhile are skipped (snoozed).

Appends notification.updated. If-Match guards the revision. Only a notification that covers this project alone changes here; one that covers other projects of the organization too is notification_covers_other_projects and changes from the organization's Notifications page.

Deletes the notification and appends notification.deleted. Its pending notices are failed with webhook_deleted; its delivery log is no longer addressable and expires with event retention. Only a notification that covers this project alone is deleted here (notification_covers_other_projects otherwise).

Webhook notifications only (any other channel is invalid_request). Replaces the signing secret and returns the notification with the new one in secret; the old secret stops signing at once, and at most one attempt already in flight may still arrive signed with the old one, so accept both briefly. Appends notification.updated with details.changed [secret].

An exact retry with the same Idempotency-Key returns the same new secret for twenty-four hours.

Appends a notification.test project event and queues one delivery of it to this notification only (no other notification receives notification.test).

A webhook receives the event as its body; an email notification sends a test email to its recipients; a Slack, Teams or Telegram notification posts a test message; a PagerDuty notification triggers an information event and resolves it at once.

It works on a disabled or snoozed notification, is attempted once without retries, and never changes the notification's failure state. Poll the deliveries log for its outcome.

The notification's delivery log, newest event first. One row per event, and per condition of that event for a screen notice; retries update the row and GET .../deliveries/{delivery_id}/attempts lists its most recent attempts. A notice that never needed sending is skipped with its reason.

Rows are retained like events (the plan's event retention, at least the 24-hour retry window). Pass next_cursor back as before for the next page.

One delivery's attempts, newest first, the most recent 20, kept with the delivery row and for as long. Each has its attempt number, when it finished, the receiver's HTTP status (null when none answered or for email), the error class (null on success) and its duration.

A delivery that is not this notification's, or a notification of another project, is not_found.

Mails an email notification's person again after they stopped it with the unsubscribe link in its mail (Notification.unsubscribed lists the people who did). Idempotent: a person who is not stopped changes nothing, and the answer is the notification as it is.

A change bumps the revision and appends notification.updated with details change resubscribed, user_id and via api. A dashboard session may resubscribe any person of the project; an agent credential needs the project write capability. The person's own way back is the Resubscribe button on the page their unsubscribe link answers with.

The link in an alert mail's footer. It carries no session and no bearer; the token t, made by screenRIG for one notification n and one person u, is the whole authority, never expires, and verifies while the issuance key version it names is retained.

The answer is a page that asks to stop that notification's mail to that person and changes nothing, so a mail scanner that opens the link stops nothing; its button posts to this path. A person already stopped sees a page whose button resubscribes.

Any token, notification or person that does not match, and a notification that is gone or is not an email notification, answers the same 404 page. The page has no script and posts only to this origin. At most 30 requests a minute per address (rate_limited).

Stops an email notification's mail to the person the link is for. The query is the one of the GET link; the body is not read, so a mail provider's RFC 8058 one-click request (List-Unsubscribe=One-Click, from the List-Unsubscribe and List-Unsubscribe-Post headers every alert and test mail carries) and the page's button both work.

Only that person is stopped, for that notification only; the others keep getting mail, and the person stays in recipients. It is idempotent. The first time it bumps the revision and appends notification.updated with details change unsubscribed, user_id and via email_link.

The page it answers has a Resubscribe button (POST /api/notifications/resubscribe); a project member lists the people stopped in Notification.unsubscribed. When nobody is left to mail, a notice is skipped as no_recipients. Any link that does not match answers the 404 page of the GET. At most 30 requests a minute per address (rate_limited).

Undoes POST /api/notifications/unsubscribe for the person the link is for: the Resubscribe button of the page it answers. Same link, same authority and same 404 page; idempotent. A change bumps the revision and appends notification.updated with details change resubscribed, user_id and via email_link. At most 30 requests a minute per address (rate_limited).