Skip to main content
@obversa/notify-webhook posts a run’s progress to your team’s channel, so nobody has to watch the run. It turns the run’s own events into one message each and posts them to the incoming webhook URL you supply. The channel sees the run start, each step finish, work go back with the reviewer’s reason, a question wait for a person, and the run end. Each body has a text field. Slack and Mattermost incoming webhooks show it with no code of your own. The rest of the body is structured, for a relay that wants the parts.

Install

Included in @obversa/obversa.

Requirements

A URL to post to, supplied at run time.

Quickstart

Make the notifier, hand its onEvent to run, and await done() before the process exits:
examples/notify-webhook.ts (excerpt)
The example starts its own receiver in place of a channel and prints the messages it received. In your own run, pass your incoming webhook’s address as url. Run it with npx tsx notify-webhook.ts:
Output

Post to your team’s Slack channel

  1. In Slack, create an app for your workspace, turn on Incoming Webhooks, and select Add New Webhook to Workspace.
  2. Select the channel your team watches, for example #releases, and allow the app to post there.
  3. Copy the webhook URL. Anyone who has the URL can post to that channel, so keep it in your secret store, not in the workflow file.
  4. Pass the URL as url when the run starts, for example from process.env.SLACK_WEBHOOK_URL.
Slack’s guide has the same steps with screenshots: Sending messages using incoming webhooks.

Other channels

Read what it sends

Six moments, one message each: The paused message names the run’s page when the run serves one, so the person can open it and answer, and asks the person’s own question when an approval() gate carries one. The page is served on the machine that runs the workflow, at 127.0.0.1, so a colleague on another computer sees the question in the channel but can’t open the link. The sent-back message carries what the reviewer said; in a graph it names the stage the work went to, and a loop names no stage because it sends work to its own body. A stage that’s waiting for a person hasn’t finished, so it’s reported as paused, and a run with two gates gets a paused message for each. A run is announced once and ends once: the first graph or loop the run reports owns it, and that container’s ending is the run’s, at whatever depth it sits. News from inside the run isn’t filtered by depth. Everything else a run emits, every engine token included, is ignored. messageFor(event, monitor?) is the mapping from one run event to a WebhookMessage ({ ts, monitor?, event, text }), or undefined for an event with no message.

Options

Errors

  • A notification that can’t be delivered never fails the run. The error reaches onError and the run carries on.
  • Order is kept. Messages are posted in the order the run made them, so one slow post holds back the rest instead of letting them overtake it.
  • A failure is reported from the ending event, never from error. A loop can emit error in one iteration and pass in the next. A resumed run sends no message of its own, because no run event says it resumed.
examples/notify-webhook.ts

API

  • webhookNotifier(options): a WebhookNotifier with onEvent and done(). Quickstart.
  • messageFor(event, monitor?): one event to one message. Read what it sends.
  • Types: WebhookNotifierOptions, WebhookMessage, MessageEvent, RunEvent, RunEventOutcome, FetchLike.

Next steps