Day to day

Get notified when an item needs you

Set up a webhook or alerts in your browser, so Kraft tells you when a work item waits at a gate or stops, and check that a test reaches you.

Set up one channel and send a test through it, so Kraft tells you when a work item needs a decision or has stopped and you do not have to watch the board.

Before you start

Kraft running, with the board open in a browser. See Install.
Nothing else for a browser alert. For a webhook, the URL of a service that accepts a JSON POST.
For a webhook, know that Kraft sends one fixed JSON body and cannot reshape it. A service that needs another format needs a receiver in between that translates it. Events shows the body.

Choose a channel

	Webhook	This browser
Sent by	The Kraft server, so no browser has to be open.	The Kraft page, so a Kraft tab has to be open.
Reaches you	In the service behind the URL.	As a system notification, while that tab is hidden.
Kept	For the whole install, in `config/notify.yaml`.	In that browser only.

You can turn on both. Each sends only for the events you chose on it.

Open Settings › Notifications and select the Webhook card. Its pane opens on the Config tab.
Paste the service's URL into Webhook URL. It must start with http:// or https://. It usually carries a token, so Kraft never shows it back. A message names the item's title, so see Data and privacy before you point it at a service you do not run.
Set Link back to an address the device reading the message can open, such as http://192.168.1.20:8765. Left empty, the link uses the address and port Kraft is bound to: http://127.0.0.1:8765 by default, which opens only on the machine Kraft runs on, and http://0.0.0.0:8765 on a server bound to 0.0.0.0, which opens nowhere.
Click Save. Kraft writes config/notify.yaml with mode 0600, and says Saved · writes notify.yaml.
Turn on Webhook notifications. It saves as you switch it. If Kraft answers set a webhook URL before enabling notifications, the URL is not saved yet: do step 4 first.
Under Notifies, switch off an event you do not want. Both are on until you do.
Under Test, click Send a test. The button works only while the webhook is on.

The line beside the button then reads like this, with the status the service answered and the time it took:

last delivered just now · 200 · 123 ms

The test sends "type": "test" and no item. The service receives the title Send a test. Kraft does not follow a redirect.

Open Kraft in the browser you want the alerts in. Open Settings › Notifications and select the This browser card. Its pane opens on the Config tab.
Read the note under Status. If it says This browser has not been asked yet., click Allow notifications and allow them in the browser's prompt. If it says Blocked in the browser's site settings., allow notifications for Kraft's address in the browser's own site settings: Kraft cannot ask again. If it says This browser has no notifications., use the webhook.
Turn on Alerts on this device.
Under Notifies, switch off an event you do not want. This browser keeps its own choice. Both are on until you do.
Under Test, click Send a test. The button works only while the switch is on and the browser allows notifications.

The test shows an alert titled Test alert with the text a decision is waiting, and the line beside the button reads last shown just now.

Keep a Kraft tab open. Alerts come from that page, and only while it is hidden, for example behind another tab or with the window minimized. Clicking an alert brings the window forward and opens the item.

On a phone, open More › Notifications. The channels are Webhook and Browser alerts, and each field saves when you edit it, with no Save button. The phone words some results differently, such as failed 1m ago: ConnectError, and its Browser alerts screen has no Notifies switches, so choosing events there is a desktop step. This guide's quoted texts are the desktop's.

What sends a notification

Settings offers two events, and nothing that reports progress.

Event	When	A browser alert says
`gate_requested`	A gate waits for your decision.	`a decision is waiting`
`work_item_needs_human`	An item stopped and waits for you, for one of the nine kinds in the first Stop kinds table.	`stopped — gate wait or cap breach`

The alert's wording is fixed and does not name the kind: read the item for that. gate is the gate event above, and wait and rate_limit send nothing, because they come from the item's status and not from this event.

A webhook message carries the item's id, title, the event type, the gate for a gate event, and a link to the item. A stop looks like this, with the base_url from step 3 in url:

{
  "work_item_id": "3f9c1e0a7b2d4c58a1e6d94b0c7f2a83",
  "title": "Fix the flaky login test",
  "type": "work_item_needs_human",
  "gate": null,
  "url": "http://192.168.1.20:8765/work-items/3f9c1e0a7b2d4c58a1e6d94b0c7f2a83"
}

A gate event has the same fields, with the gate's name in gate, such as spec_approval. Events has the gate body, and what a webhook does when a send fails or events come close together.

A browser alert for that stop has the item's title as its title and stopped — gate wait or cap breach as its text. For a gate the text is a decision is waiting.

Check it worked

Webhook. The line beside Send a test reads last delivered with a status from 200 to 299, and the message arrives in the service. The next time an item reaches a gate, a POST arrives whose title is the item's title and whose url opens the item. kraft view show ID names the same stop. A status outside that range is explained in If nothing arrives.
This browser. The line beside Send a test reads last shown, and an alert titled Test alert appears.

If nothing arrives

The texts are the desktop's. On a phone, the webhook's dimmed button says Turn on the webhook and set a URL first., and a failed test reads failed 1m ago: ConnectError.

What you see	What it means	Fix
Send a test is dimmed, with `set a webhook URL first`	No URL is stored.	Do steps 2 to 5 of the webhook tab.
Send a test is dimmed, with `set the channel active first`	A URL is stored, but the switch is off.	Turn on Webhook notifications.
`url must be an http or https URL`, or the same for `base_url`	The address has another scheme, such as `file:`.	Use a full `http://` or `https://` address.
`last attempt 1m ago, failed: ConnectError`	Kraft could not reach the URL. The line names the kind of error, never the address.	Check the URL and that the server can reach the service.
`last delivered` with a status that is not 2xx	The service answered, and did not take the message. The test says `delivered`, and a toast says `Test sent to the webhook`, for any answer, a redirect or a `404` included.	Read the status: the service did not accept the URL or the body. A service that wants its own format needs a receiver in between.
The test works, but no message comes for an item	Kraft sends one message per item every 10 seconds, only for the events you chose, and never for events from while the server was down.	Check Notifies. After a failed send, the item's timeline holds a `notification_failed` event: `kraft view events ID --type notification_failed`.
A hand edit of `notify.yaml` changes nothing, though Settings shows it	A running server reads the file only when a setting is saved or at start, and Settings shows what is on disk meanwhile.	Change a setting that saves on its own, such as switching an event off and back on, or run `kraft admin restart`. Save stays dimmed until you edit a field.
The log says `notify.yaml: ... -- notifications disabled until it is fixed`	Kraft could not use the file, so it sends nothing. The text before the dashes is `not valid YAML`, `cannot be read`, or a key and its problem, such as an unknown key.	Fix the file, then restart. Logs and disk space says where the log is.
The browser's Send a test is dimmed, with no hint	It works only while Alerts on this device is on and the browser allows notifications.	Do steps 2 and 3 of the browser tab. On a phone, only the permission is needed.
No browser alert, though the test worked	Alerts show only while the Kraft tab is hidden, and only while it is open.	Switch to another tab or window, and leave the Kraft tab open.

Next steps

Notifications: the JSON body, how a failed send is retried, and the notification_failed event.
notify.yaml: every field, and the events a hand edit can add.
Why did my item stop?: what each stop means and how to get the item going again.
Kraft on a phone: the phone layout, if that is where the alerts go.

Edit this pageorReport an issue

Kraft on a phone

The phone layout, with its bottom bar, the board's filters and cards, and the buttons on a stopped item.

Write your own chain

Add a lint node to a copy of the default chain, with an agent that fixes what lint reports, a time cap, and no way to skip it.