# Notifications and activity

See what needs you in the inbox, by email and from the CLI, follow events live, send webhooks and take back an action.

## What needs you

```sh
sailfork status
sailfork events --since 2h
sailfork events --follow --types review,comment,ci
```

`sailfork status` lists what is waiting on you right now. `sailfork events` prints what happened, and with `--follow` keeps printing as it happens.

## The inbox

`/notifications` shows **All inboxes**, with a link to each workspace's inbox and its unread count. `/{owner}/inbox` shows one: your own (**Personal**), or an organization you belong to.

The inbox has two tabs, each with a count:

- **For you**: issues assigned to you, mentions of you, reviews, and caisson writes held for your approval. In an organization's inbox, open pull requests you did not open and have not reviewed lead the list, and choosing one lets you **Approve**, **Approve and merge** (when checks pass and nothing holds it back) or **Request changes** without leaving the inbox.
- **Following**: comments and status changes on issues you follow, and updates from agents working on them.

Opening a notification takes you to where it happened and marks it read. **Mark all read** clears the tab. With the keyboard, `J` and `K` (or the arrow keys) move through the list and `E` marks one read.

CI that deployed to an environment, or that you started by hand, tells you when it ends. A mirror that stops or holds back a branch also lands here.

### What you follow

You follow an issue when you create it, are assigned to it, comment on it (unless you turn that off) or are `@mentioned` on it. `sailfork issue subscribe 7` and `sailfork issue unsubscribe 7` change it from the terminal, and the issue page has a **Following** control. Mentions are covered in [Issues](https://status.sailfork.com/docs/issues#mentions).

## Email

The **Notifications** page in your settings decides what also reaches you by email. Everything lands in the inbox either way.

| Setting | Choices |
| --- | --- |
| **For you** (issues assigned to you and mentions) | Email now, Daily digest, Inbox only, Off |
| **Following** (comments and status changes on issues you follow) | Inbox and email, Inbox only, Off |
| **Agent activity** (updates from agents on issues you follow) | Inbox and email, Inbox only, Off. With email on, each agent can be muted by name. |
| **Follow issues you comment on** | On or off |
| **A mirror stops or holds back a branch** | Inbox and email, Inbox and digest, Inbox only, Off |
| **Following and agent email** timing | Send now, Daily digest, Hold and send nothing |
| **Daily digest arrives at** | An hour, in your time zone |
| **Quiet hours** | Email waits until they end. The inbox keeps filling. |

Security and billing email is always sent.

## The activity feed

An organization's **Activity** page shows the latest pushes, reviews and merges across its repositories, by people and by agents, with who did it and how long ago.

## From the CLI

### status

`sailfork status` shows three sections: **Your pull requests** with their state, checks and review, **Waiting for your review**, and **Assigned to you**. It says "Nothing needs you right now." when all are empty, and points at `sailfork pr checks` when a pull request of yours has failing checks. Each section shows up to 50 rows. `-R fenil/ocean-landing` limits it to one repository, and `--json` is for scripts.

### events

`sailfork events` prints reviews, comments, CI, merges and pushes on your repositories.

```sh
sailfork events --since 2h
sailfork events --org acme --types review,comment --follow
sailfork events --limit 20 --json
```

| Flag | What it does |
| --- | --- |
| `-f, --follow` | After the history, keep printing new events until you interrupt it. The cursor to resume from goes to stderr. |
| `--org <HANDLE>` | Every repository of this user or organization, instead of `-R` or the current clone. |
| `--types <LIST>` | Comma separated: `review`, `comment`, `ci`, `mention` (mentions of you), `merge`, `push`, `issue`, `pull`, `caisson`. |
| `--since <WHEN>` | A cursor printed earlier, an RFC 3339 time, or a duration ago such as `30m`, `2h` or `7d`. Default: the last 30 days, or with `--follow` only new events. |
| `--limit <N>` | Stop after this many events and print the cursor to continue from. |

Every event printed moves the cursor, so `--since <cursor>` continues with no gap and no repeat. Events are kept for 30 days. Each event names the repository, the issue or pull request number, the actor, the agent name when an agent acted, and a finer verb such as `pull.review`, `pull.merge` or `run.fail`.

The same feed is `GET /api/events` for history and `GET /api/events/stream` for a live `text/event-stream`. A signed-out request must name a `repo` or `org`. See [the API reference](https://status.sailfork.com/docs/api).

## Webhooks

A repository admin can send a signed request to a URL of their own when something happens. Add one in the repository's settings, under **Webhooks**, or with `POST /api/repos/{owner}/{repo}/hooks`.

- Events: `push`, `pull_request` (opened, closed, merged, reopened) and `ci_run` (completed). The default is all three.
- The URL is `http` or `https`, at most 2048 bytes, with no username or password, and must be a public address. Localhost and private addresses are refused. A repository has at most 20 webhooks.
- The signing secret (`whsec_...`) is shown once, when you create the hook.
- Each delivery is a JSON `POST` with `X-Sailfork-Event`, `X-Sailfork-Delivery` and `X-Sailfork-Signature-256`, which is `sha256=` and the hex HMAC-SHA256 of the raw body under the secret.
- Any 2xx answer is delivered. Anything else, a refused connection or no answer within 10 seconds is retried after 10 seconds, 1 minute, 5 minutes and 30 minutes, then marked failed. Redirects are not followed.
- A `ping` delivery is sent when you create the hook. Deliveries are kept for 30 days and can be redelivered.

```sh
curl -X POST https://status.sailfork.com/api/repos/fenil/ocean-landing/hooks \
  -H "Authorization: Bearer $SAILFORK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hook","events":["pull_request","ci_run"]}'
```

Body fields and the rest of the hook routes are in [the API reference](https://status.sailfork.com/docs/api).

## Take back an action

`sailfork undo` reverses your most recent action:

```sh
sailfork undo --dry-run
sailfork undo --yes
sailfork undo --list
sailfork undo 6f1c2a9e-0d4b-4c51-9a77-2f0e8b1d3c55 --yes
```

`--list` shows your recent actions with their ids and whether each can still be undone (`--limit`, default 20). `--dry-run` says what would happen and changes nothing. `--yes` confirms when there is no terminal to ask on.

What can be undone, within 24 hours and once:

- A comment on an issue or pull request, which is deleted.
- A change to an issue or pull request: labels, assignee, status, close or reopen, title and body, restored to their old values.
- A merge: the base branch moves back, the branch is recreated and the pull request reopens.
- A deleted branch, recreated at its old commit, and a file removed in a caisson, written back.
- A token you created, which is revoked.

Actions are listed for 7 days. An undo is refused with 409 and the reason when the action is older than 24 hours or the thing changed again since. A merge that was not a fast-forward, or that the base branch has moved past, cannot be undone this way, and the message gives the git commands for a revert pull request. Undoing an action twice answers with the first result.

## Who sees what

- Your inbox, email settings and `sailfork status` are yours alone.
- Anyone who can read a repository can read its events. A token needs `repo:read`.
- Webhooks, and their deliveries, are for repository admins.
- A person only gets a notification about an issue if they can read the repository.

---

Every docs page: https://status.sailfork.com/llms.txt
