Automations Guide

Webhook

A unique signed URL per automation. Anything POSTed to it is HMAC-verified, deduped, rate-limited, and (if accepted) enqueued as a run. Use this when an external service has webhook output (GitHub, Linear, Sentry, Stripe, your own forms).

Schedule

Standard 5-field cron expression. Use this for recurring rollups (weekly leadership digest, daily team summary) or polling external sources that don't push webhooks. The payload is empty {} — the recipe pulls its inputs via MCP tools.

Template context

When a recipe runs, the template is evaluated against a tiny data map. The only top-level keys are:

There is no other top-level data. No .automation, no .recipe, no .trigger, no implicit timestamps, no template functions like now or json. If the recipe needs additional context — the current user, related workunits, your project's recent activity — it pulls that via MCP tools at run time. The template is the prompt, not the orchestrator.

Payload by trigger

{{.payload}} is the same variable everywhere, but what it contains depends on the trigger type:

{
  "event": "issue.created",
  "issue": {
    "id": "ISS-1234",
    "title": "Login button broken on Safari",
    "labels": ["bug", "frontend"]
  }
}

{
  "scheduled_for": "2026-05-26T09:00:00Z"
}

Gotchas

Worked example

A Linear-bug-triage recipe might look like this. The template uses both substitution sites — the payload for the actual issue data, the config to scope the triage to the right project and team.

You are triaging a Linear issue for the {{.cfg.team_name}} team
on the Workunit project {{.cfg.project_id}}.

The issue webhook payload is:

{{.payload}}

Steps:
1. Read the issue title and labels.
2. If the labels include "bug", create a Workunit under project {{.cfg.project_id}}
   with the issue title as the problem statement.
3. {{if .cfg.notify_user}}Notify {{.cfg.notify_user}} once the workunit exists.{{end}}
4. Save a context atom on the new workunit summarising what you found.

Return a short JSON object with {workunit_id, action_taken}.

An automation built on this recipe sets its Config to something like:

{
  "team_name": "Frontend",
  "project_id": "d44037bb-315f-43cb-a60e-b387b4ffeec4",
  "notify_user": "[email protected]"
}

When Linear POSTs an issue-created event, the recipe agent sees the rendered prompt with the issue's title, labels, and IDs interpolated alongside the config-supplied project_id and team_name — then it has the MCP tools it was allowed to call (create_workunit, search, save_context) to do the actual triage.

Signature schemes

Every webhook endpoint at /hooks/<path_token> uses a signature scheme to verify requests. The scheme is set when the automation is created — pick a recipe matching your source (GitHub, Stripe, Linear, Sentry, Shopify) and the verifier is locked to that vendor's format. Custom senders use the Workunit-native scheme below.

Signing — curl

# Replace PATH_TOKEN and SECRET with the values from your automation row.
PATH_TOKEN=your-43-char-base64url-path-token
SECRET=your-hmac-secret
BODY='{"ping":"pong"}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

curl -X POST "https://workunit.app/hooks/$PATH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-WU-Timestamp: $TS" \
  -H "X-WU-Signature: $SIG" \
  --data-raw "$BODY"

Signing — Node.js

// Node.js 18+ (uses the built-in fetch + crypto modules).
import { createHmac } from 'node:crypto';

const pathToken = 'your-43-char-base64url-path-token';
const secret = 'your-hmac-secret';
const body = JSON.stringify({ ping: 'pong' });
const ts = Math.floor(Date.now() / 1000).toString();
const sig = createHmac('sha256', secret).update(`${ts}.${body}`).digest('hex');

const res = await fetch(`https://workunit.app/hooks/${pathToken}`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-WU-Timestamp': ts, 'X-WU-Signature': sig },
  body,
});
console.log(res.status, await res.text());

Signing — Python

# Python 3.10+
import hmac, hashlib, json, time, urllib.request

path_token = "your-43-char-base64url-path-token"
secret = b"your-hmac-secret"
body = json.dumps({"ping": "pong"}).encode()
ts = str(int(time.time())).encode()
sig = hmac.new(secret, ts + b"." + body, hashlib.sha256).hexdigest()

req = urllib.request.Request(
    f"https://workunit.app/hooks/{path_token}", data=body, method="POST",
    headers={"Content-Type": "application/json", "X-WU-Timestamp": ts.decode(), "X-WU-Signature": sig},
)
with urllib.request.urlopen(req) as resp:
    print(resp.status, resp.read().decode())

Signing — Go

package main

import (
	"bytes"; "crypto/hmac"; "crypto/sha256"; "encoding/hex"; "fmt"
	"net/http"; "strconv"; "time"
)

func main() {
	pathToken, secret := "your-43-char-base64url-path-token", []byte("your-hmac-secret")
	body := []byte(`{"ping":"pong"}`)
	ts := strconv.FormatInt(time.Now().Unix(), 10)
	mac := hmac.New(sha256.New, secret); mac.Write([]byte(ts + ".")); mac.Write(body)
	sig := hex.EncodeToString(mac.Sum(nil))

	req, _ := http.NewRequest("POST", "https://workunit.app/hooks/"+pathToken, bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("X-WU-Timestamp", ts); req.Header.Set("X-WU-Signature", sig)
	resp, _ := http.DefaultClient.Do(req); defer resp.Body.Close()
	fmt.Println(resp.Status)
}

HTTP status codes

• 202 Accepted — delivery persisted; run enqueued (or deduped/rate-limited per the automation's own settings — see the response body)
• 401 Unauthorized — signature missing, wrong, outside the timestamp skew window, OR the path_token doesn't exist. Collapsed deliberately so the response can't be used to enumerate which tokens exist — the precise failure mode is recorded in the delivery audit row for the owner to debug.
• 413 Payload Too Large — body exceeded the 256 KB cap (rejected pre-R2 write)
• 429 Too Many Requests — the endpoint hit the pre-signature ceiling of 60 requests/minute. The cap is a fixed DoS guard and applies BEFORE signature verification, so a flood of bad-signature requests trips it too. Back off ~1 minute and retry; legitimate senders rarely exceed it.
• 503 Service Unavailable — transient backend hiccup (e.g. R2 storage outage). Honor the Retry-After header.

Dedup & rate limits

There are three independent ceilings on a webhook endpoint, applied in this order:

1. Pre-signature ceiling (60/min, fixed) — any request, valid or not, counts. Trips return 429 BEFORE signature verification and don't write an audit row. This is a DoS guard, not a tunable.
2. Dedup — JSONPath + window seconds, configured per automation. Matching deliveries are accepted (audit row + R2 write) but don't fire a run. Set a JSONPath like $.event.id and a window like 86400 to suppress repeats of the same external event for 24 hours.
3. Per-automation rate limit (runs/minute, tunable) — counts every delivery that LED to a run. Trips return 202 with rate_limit_dropped: true in the response body — the sender's retry queue is satisfied but no run fires. Set this to whatever your downstream workflow can absorb.

The pre-signature ceiling exists because every bad-signature request still costs a DB INSERT for the audit row, and a known endpoint UUID is enough for an attacker to amplify writes. 60/min is well above any normal webhook source's cadence (Stripe, GitHub, Linear, Sentry all batch into low tens per minute). If a legitimate sender sustains higher than that, talk to us; raising the ceiling is a code change.

Test-fire (the button on each automation row) has its own modest cap of 10 fires per minute per automation — admin sessions still cost model spend, and the cap stops accidental scripts. Use the real webhook path for load testing.