608 - Results out: notification channels and signed delivery to other systems

• 601Do not spend AI on what a script can doThe automation gap, what integration platforms and laptop scripts each cost, and the division of labor: a script for the deterministic part, the model for writing it and for judgment.
• 602The agent writes the first scriptThe loop from a recorded draft through tests to the save, what a save requires, what validate and a dry run report, the dialect’s deliberate absences, the traps that fail a draft, and the script’s page in the portal.
• 603Outputs: feeds, reports, and dashboards that refresh themselvesOutput identity across runs, tables and documents, the semi-dynamic dashboard and its data region, the referencing pattern, version caps, and delivery to a bucket drop.
• 604Running it: by hand, from the portal, and on a scheduleThree triggers, the cadence builder, the pinned fire date, what a schedule guarantees, and the run history with every trigger, duration, output, and log.
• 605What a run may do, and the record it leavesThe authority a run carries, what a save refuses, why the language cannot reach out, the lifecycle, ownership and transfer, and the administrator’s view.
• 606Scripts as skills: the weekly review the agent runs on your businessThree scripts attached to one prompt, the agent running them and reading the outputs against the knowledge graph, and a weekly list of action items with the figures behind them.
• 607Events in: a webhook source, its table, and an automation that reads itCreating a source, how a sender proves itself and what it is told, the table that serves events from acknowledgement, compaction and retention, the Webhooks page, and an automation that reads only what is new.
• 608Results out: notification channels and signed delivery to other systemsChannel kinds and who may send to them, sending from a session and from an automation, the delivery history and the retry rule, the JSON envelope a system routes on, signed requests, and delivery to another deployment.

Email list

One to twenty recipient addresses, and no connection.

A subject, the body, and a button that opens the link. Each recipient gets their own copy, so each keeps their own delivery mode, daily digest, and unsubscribe link: one person opting out silences nobody else.

Mattermost

An API connection holding the bot’s token and the site address, and the id of the chat channel to post in.

A title, the markdown body, and the link, as a post from the bot.

Incoming webhook

An API connection whose address is the webhook’s URL, and a format: Text or JSON.

Text posts the title and body as one message, the form chat incoming webhooks accept. JSON posts an envelope for a system: every field, the body whole, and the sender’s structured data.

People

store-ops

An email list: “Store operations team: failed automations and daily sales alerts”. Immediate delivery, up to 60 messages an hour.

Systems

ops-events

An incoming webhook in JSON format: “Operations event feed for systems”. It delivers through the API connection acme-ops-events, which signs every request.

The receiver

ops-events webhook source

A source created under Admin > Webhooks that accepts only requests carrying a valid signature and a fresh timestamp, takes the envelope’s id as the event id and its type as the event type, and writes each delivery to scratch.uploads.webhook_ops_events.

An automation

ACME returns alert (lesson 608)

Written for this lesson. Each run reads the last 24 hours of the point-of-sale feed from lesson 607 and tells both channels which stores reached a threshold of returns.

1. 1

   Name and description

   The name is what a person or a script sends to. The description is shown to anyone choosing between channels, so it says who reads the channel and what belongs in it.

2. 2

   Kind, and what the kind needs

   Email list, Mattermost, or Incoming webhook. An email list takes its recipients; the other two take the API connection they deliver through, plus the chat channel id for Mattermost and the format for a webhook.

3. 3

   Enabled

   A disabled channel refuses what is sent to it instead of collecting messages nobody will deliver.

4. 4

   Daily digest and messages per hour

   A channel can collect a day’s messages into one bulletin instead of delivering each as it is sent; the channel decides, and a sender cannot override it. Messages per hour caps how much one channel carries.

5. 5

   Send test

   Delivers a test message at once through the channel’s own path and reports what the receiving end said, so a wrong address, a revoked token, or a receiver that rejects the signature shows in the editor, not in somebody’s run.

• A person, through their agent

  The notify tool: list, send, publish

  List shows the channels this session can reach. Send posts a title, a markdown body, an optional link, and for a JSON webhook optional structured data. Publish posts a saved asset: its title, an excerpt, and a link to it.

• An automation

  notify and publish from the script

  The run sends as the script, with the roles its author held at the save. The post links back to the run that produced it unless the script names its own link. A rehearsal run does not post unless it is told it may write.

• An administrator

  Send test on the channel’s editor

  Delivers a test at once, through the same path as every other message, and reports the receiving end’s answer.

notify  action list

-> store-ops   email     immediate
               "Store operations team: failed automations and daily sales alerts"

notify  action send
  channel  ops-events
  title    Three stores at four returns in the last 24 hours
  body     Stores 175, 89 and 276 each logged **4 returns** in the last
           24 hours of the point-of-sale feed, the most of any store. …
  data     {"window_hours": 24, "stores": [{"store_id": 175, "returns": 4,
            "returned_amount": 740.6}, …]}

-> queued     1
   delivered  false
   detail     accepted for delivery to "ops-events"; an administrator can
              see the outcome in the platform's notification history

def main():
    threshold = run.params.get("threshold", 4)
    rows = stores_over(threshold, run.fire_time)
    if not rows:
        platform.result({"stores": 0, "notified": []})
        return
    title, body = summary(rows, threshold)
    data = {
        "window_hours": 24,
        "threshold": threshold,
        "stores": [{"store_id": int(r["store_id"]), "returns": int(r["returns"]),
                    "returned_amount": float(r["returned_amount"])} for r in rows],
    }
    platform.notify("store-ops", title, body)
    platform.notify("ops-events", title, body, data = data)
    platform.result({"stores": len(rows), "notified": ["store-ops", "ops-events"]})

# stores_over reads the 24 hours before the fire time from
# scratch.uploads.webhook_pos_sales, one row per event id,
# and keeps the stores at or above the threshold.

run_script  name acme-returns-alert-608

-> status    succeeded
   trigger   tool
   result    {"stores": 6, "notified": ["store-ops", "ops-events"]}
   log       notify: send to store-ops: accepted for delivery to "store-ops"
             notify: send to ops-events: accepted for delivery to "ops-events"

14

Sent

0

Pending or sending

0

Failed

30 days

How long the history keeps a row

Recipient

An address for an email, channel:ops-events for a channel delivery.

Category

channel for these sends, beside shares, comments, mentions, and failed automation runs.

Subject

The message title.

Status and attempts

Pending, sending, sent, or failed, and how many tries.

Error

On a failed row, opened from the list: what the receiving end said, in its own words.

1. 01

   Five attempts at most

   A delivery that fails in a way that may pass later (a timeout, a refused connection, an error on the receiving server, a rate limit) is tried again, up to five attempts in all.

2. 02

   Waits of 30 seconds, then 1, 2, and 4 minutes

   The wait doubles after each failed attempt. A row that fails its fifth attempt is marked failed with the last error recorded on it.

3. 03

   The receiver’s retry hint is honored, up to 32 minutes

   A receiver that answers 429 or 503 with a Retry-After is waited for as long as it asks, up to 32 minutes, the longest wait the queue ever makes.

4. 04

   410 Gone stops at once

   A receiver that says the destination is gone gets no further attempts, and the row records that it asked for no more deliveries.

5. 05

   A refusal stops at once

   Any other 4xx answer, a deleted or disabled channel, a revoked token, or a chat channel the bot was never invited to fails the row on the first attempt, with an excerpt of the answer, instead of trying five times to say the same thing.

6. 06

   A retry carries the same id

   Every attempt of one message carries the same envelope id, so a receiver that saw the first attempt arrive but whose answer was lost recognizes the second as a copy.

{
  "id": "ntf_34",
  "type": "script.finding",
  "occurred_at": "…T00:34:17.628459Z",
  "deployment": "Plexara",
  "channel": "ops-events",
  "title": "6 stores at 4 or more returns in the last 24 hours",
  "body": "- Store 175: 4 returns, $740.60\n- Store 89: 4 returns, $376.57\n…",
  "link": "https://mcp-demo.plexara.io/portal/automations/db041ffa…/runs/dpx_e123017f…",
  "source": {"kind": "script", "script": "mcp:script:db041ffa…", "run_id": "dpx_e123017f…"},
  "data": {"window_hours": 24, "threshold": 4,
           "stores": [{"store_id": 175, "returns": 4, "returned_amount": 740.6}, …]}
}

id

The same on every attempt of one message, and the field a receiver dedupes on. A test send gets a new id each time.

type

What produced it, and the field a receiver routes on: script.finding or script.published from an automation, notify.sent or notify.published from a person, test from Send test.

source

The script and the run for an automation, user for a person, admin for a test.

data

The sender’s structured payload, exactly as sent, up to 64 KiB. Only a JSON webhook channel carries it.

deployment, channel

Which deployment and which channel sent it, for a receiver fed by several.

• Standard Webhooks

  Signs the message id, the timestamp, and the body, in base64, with the id, timestamp, and signature in the headers that standard names. A whsec_ secret is read the way the standard reads it.

• GitHub

  Signs the body with SHA-256 in hex, written as sha256= followed by the signature, in the header GitHub receivers check.

• Stripe

  Signs the timestamp and the body, and writes both into one signature header in Stripe’s layout.

• Platform

  Signs the timestamp and the body with SHA-256 in hex, the convention a Plexara webhook source verifies. This is what the demo’s acme-ops-events uses.

trino_query
  connection  scratch
  sql   SELECT event_id, event_type, json_format(json_extract(payload, '$.source')) AS source,
               json_array_length(json_extract(payload, '$.data.stores')) AS stores
        FROM scratch.uploads.webhook_ops_events ORDER BY received_at

-> event_id                      event_type      source                                     stores
   ntf_test_1791419459535200988  test            {"kind":"admin"}                           -
   ntf_29                        notify.sent     {"kind":"user"}                            3
   ntf_32                        script.finding  {"kind":"script","run_id":"dpx_80632f9e…"}  6
   ntf_34                        script.finding  {"kind":"script","script":"mcp:script:…",  6
                                                  "run_id":"dpx_e123017f…"}

1. 01

   Verify over the raw body

   Compute the signature over the bytes exactly as they arrived, before parsing them. Parsing and re-encoding changes the bytes and the signature no longer matches.

2. 02

   Refuse a stale timestamp

   A request whose timestamp is more than a few minutes from the receiver’s clock is refused even when its signature is right. That makes a captured request useless to replay.

3. 03

   Drop an id already seen

   Answer it with success and do nothing. Delivery is at least once, and the id is the same on every attempt.

4. 04

   Route on type, read data

   The title and body are for people. A system branches on type and reads the fields it needs from data.

5. 05

   Answer with the right status

   Any 2xx once the message is safely kept. 429 or 503 with a Retry-After to be asked again later. 410 to stop deliveries for good. Anything else is taken as a refusal and not retried.