@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
@obversa/obversa.
Requirements
A URL to post to, supplied at run time.Quickstart
Make the notifier, hand itsonEvent to run, and await done() before
the process exits:
examples/notify-webhook.ts (excerpt)
url.
Run it with npx tsx notify-webhook.ts:
Output
Post to your team’s Slack channel
- In Slack, create an app for your workspace, turn on Incoming Webhooks, and select Add New Webhook to Workspace.
- Select the channel your team watches, for example
#releases, and allow the app to post there. - 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.
- Pass the URL as
urlwhen the run starts, for example fromprocess.env.SLACK_WEBHOOK_URL.
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
onErrorand 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 emiterrorin one iteration and pass in the next. A resumed run sends no message of its own, because no run event says it resumed.
Full file
Full file
examples/notify-webhook.ts
API
webhookNotifier(options): aWebhookNotifierwithonEventanddone(). Quickstart.messageFor(event, monitor?): one event to one message. Read what it sends.- Types:
WebhookNotifierOptions,WebhookMessage,MessageEvent,RunEvent,RunEventOutcome,FetchLike.
Next steps
- Watch a run in the browser: the page a paused message links to.
- Running: the events every run emits.