Get notified when an item needs 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

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

last delivered just now · 200 · 123 ms

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 three events, and nothing that reports progress.

A browser that never chose its events alerts for all three. A webhook's events list in notify.yaml is explicit, so add work_item_storage_held to it to be told.

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.

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.