WEBHOOKS
The --webhook flag on swamp serve registers an HTTP endpoint that triggers a
workflow when an incoming request arrives. The flag is repeatable — pass it
multiple times to register several endpoints.
Spec format
On the CLI, webhooks use a colon-delimited string:
--webhook '<route>:<workflow>:<secret>[:<scheme>[:<header>[:<prefix>]]]'In a config file, each webhook is a YAML object with named fields instead of the colon-delimited format.
| Field | Required | Description |
|---|---|---|
route |
Yes | URL path for the endpoint (e.g., /hooks/github). A serve.yaml or --webhook route may be any path that starts with /, including one under /api/; only the leading slash is checked. A route file's route must sit under /hooks/ |
workflow |
Yes | Workflow to trigger on valid requests |
secret |
Yes | Signing secret or secret indirection reference |
scheme |
No | Provider scheme (default: github). See Provider schemes |
header |
No | Custom header name (generic scheme only) |
prefix |
No | Expected value prefix (generic scheme only) |
config |
No | Object passed to an extension scheme's handler. Config files only; refused for built-in schemes |
Provider schemes
Each scheme defines how the incoming request signature is verified.
| Scheme | Algorithm | Signature header | Notes |
|---|---|---|---|
github |
HMAC-SHA256 | X-Hub-Signature-256 |
Default when scheme is omitted |
linear |
HMAC-SHA256 | Linear-Signature |
|
stripe |
HMAC-SHA256 | Stripe-Signature |
Stripe signing protocol (timestamp + payload) |
slack |
HMAC-SHA256 | X-Slack-Signature |
|
jira |
HMAC-SHA256 | X-Hub-Signature |
sha256= prefix (same HMAC as GitHub) |
generic |
HMAC-SHA256 | Custom (via <header>) |
Requires a header name; optional prefix |
Secret sources
The <secret> field supports indirection so signing secrets do not appear as
literal values in process arguments.
| Prefix | Source | Example |
|---|---|---|
@env=VAR_NAME |
Environment variable VAR_NAME |
@env=WEBHOOK_SECRET |
@file=/path |
File contents (trailing newline trimmed) | @file=/run/secrets/webhook |
@vault=<name>:<key> |
Named vault key | @vault=prod-secrets:webhook-key |
| (plain string) | Literal value (backward compatible) | mysecret |
The server reads the resolved secret at startup. If the environment variable is unset or the file cannot be read, the server refuses to start.
CEL context
When a workflow is triggered by a webhook, the webhook.* namespace is
available only while the workflow's trigger.inputs is evaluated. A webhook.*
reference in a step input or a guard fails with Unknown variable: webhook. Map
payload fields to inputs in trigger.inputs and read inputs.<name> in steps.
| Field | Type | Description |
|---|---|---|
webhook.body |
dyn |
Parsed JSON body (object or array), or raw string for non-JSON payloads |
webhook.headers |
map<string, string> |
Request headers, names lowercased; signature and credential headers removed |
webhook.route |
string |
Matched route path |
trigger:
inputs:
action: "${{ webhook.body.action }}"
event: '${{ webhook.headers["x-github-event"] }}'Examples
GitHub (default scheme)
swamp serve --webhook '/hooks/github:on-push:@env=GITHUB_WEBHOOK_SECRET'Linear
swamp serve --webhook '/hooks/linear:on-issue:@env=LINEAR_SECRET:linear'Stripe
swamp serve --webhook '/hooks/stripe:on-payment:@env=STRIPE_WEBHOOK_SECRET:stripe'Slack
swamp serve --webhook '/hooks/slack:on-command:@env=SLACK_SIGNING_SECRET:slack'Jira
swamp serve --webhook '/hooks/jira:on-issue:@env=JIRA_WEBHOOK_SECRET:jira'Generic
swamp serve --webhook '/hooks/custom:on-event:@env=CUSTOM_SECRET:generic:X-Custom-Token:Bearer'The generic scheme computes an HMAC-SHA256 digest of the request body using
the resolved secret as the key, then compares it against the value of the
X-Custom-Token header (after stripping the Bearer prefix).
Extension webhook schemes
Webhook schemes of the form @collective/name are resolved from installed
extensions. The extension must export a webhook handler (see
Webhook kind). Trusted
collectives are auto-pulled on first reference.
serve.yaml format
webhooks:
- route: /hooks/telegram
workflow: on-message
secret: "@env=TELEGRAM_SECRET"
scheme: "@swamp/telegram"
config:
botName: my-botThe config object is passed to the extension handler's
createHandler(config). When configSchema is declared in the handler, the
config object is validated at startup.
CLI format
swamp serve --webhook '/hooks/telegram:on-message:@env=TELEGRAM_SECRET:@swamp/telegram'The CLI format does not support the config object. Use a config file when the
handler requires configuration.
Handler lifecycle
- The server resolves the extension scheme and calls
createHandler(config). - On each incoming request,
verify(body, headers, secret)runs first. Afalsereturn or a thrown error responds 401. Verification is fail-closed: any error rejects the request. - Hooks fire only after successful verification — a failed verify never triggers hooks.
- If
transform(body, redactedHeaders)is defined, the transformed payload replaces the raw body for downstream processing. - If
respond(payload)is defined, its return value ({ status, headers?, body?, enqueue }) controls the HTTP response and whether the workflow run is enqueued. Withoutrespond, the default 200 response and enqueue behaviour applies.
There is no handler timeout — the server does not impose a deadline on verify,
transform, or respond. Response headers returned by respond are passed
through unfiltered.
@swamp/telegram
First-party extension for receiving Telegram bot updates.
Telegram uses a static secret token sent in the
X-Telegram-Bot-Api-Secret-Token header. The handler compares it to the
configured secret using constant-time comparison. This is weaker than HMAC — the
secret is transmitted in the clear (not derived from the body), so TLS is
required. Do not use over plain HTTP.
webhooks:
- route: /hooks/telegram
workflow: on-telegram
secret: "@env=TELEGRAM_BOT_SECRET"
scheme: "@swamp/telegram"Set the webhook on the Telegram side with the matching secret_token:
curl -X POST "https://api.telegram.org/bot$BOT_TOKEN/setWebhook" \
-d "url=https://swamp.example.com/hooks/telegram" \
-d "secret_token=$TELEGRAM_BOT_SECRET"Route files
A route file defines one webhook route in a YAML file committed to the
repository. Approving a route file in review approves its workflow, scheme and
secret reference. Runs are authorized as service:webhook, like any other
route. Extensions cannot register routes. See
Add a route through a route file.
Directory
| Setting | Config key | Environment variable | Default |
|---|---|---|---|
--webhook-routes-dir <path> |
webhook-routes-dir |
SWAMP_WEBHOOK_ROUTES_DIR |
webhook-routes |
--webhook-routes-poll <dur> |
webhook-routes-poll |
SWAMP_WEBHOOK_ROUTES_POLL |
off |
A relative directory resolves against the repository. Only *.yaml and *.yml
files at the top level of the directory are read. The directory may not be, or
sit inside, extensions/, the repository's webhook extensions directory or
.swamp/. Serve then loads no route files, reports the directory once, and
starts with its other routes.
Fields
A route file holds one mapping with the fields of a
config file webhook entry: route, workflow, secret,
scheme, header, prefix, config. An unknown key refuses the file. The
secret must be @vault=<vault>:<key>; a literal, @env= or @file= secret
refuses the file.
File limits
A file is refused when it:
- is larger than 64 KiB
- uses YAML anchors or aliases
- nests deeper than 32 levels
- is not a regular file
- is a symlink whose target is outside the directory
- claims the same route as another file (both files are refused)
Route rules
| Route | Refusal reason as serve prints it |
|---|---|
Not under /hooks/ |
the route is not under /hooks/, which route files require |
The bare /hooks/ prefix |
the route is the bare /hooks/ prefix; name a route under it |
| An empty segment | the route has an empty segment |
A . or .. segment |
the route has a '.' or '..' segment, which no request path can match |
A character outside letters, digits and -._~ |
the route has segment '<segment>' with characters other than letters, digits and '-', '.', '_', '~' |
Each refusal is printed as
Refused webhook route file <file> (route <route>): <reason>. A refused route
refuses only that file, and is reported at startup, on reload and by
swamp serve check-config.
Loading
Each file is parsed on its own, including vault lookup and extension scheme resolution. A refused file never stops serve or the other routes.
| Event | Behavior |
|---|---|
| Startup | Loads every file. A vault that cannot answer refuses the file |
swamp serve reload or a poll |
Re-reads every file. A file whose edit stops it loading keeps its last good route |
| Vault outage on reload or poll | An unchanged file keeps its live route. A missing key, a refused read or an edited file drops the route |
| File deleted | Its route is removed on the next reload or poll |
| Poll | Applies a change once two polls see the same files. Changes only route-file routes. The interval is read at startup |
--webhook-routes-poll takes whole seconds or larger units (minimum 1s) or
off.
Precedence
A serve.yaml or --webhook route on the same path wins, and the route file is
reported as shadowed:
Webhook warnings:
! Shadowed webhook route file good.yaml (route /hooks/github): the serve config defines the same route, which serve uses insteadswamp serve check-config fails on a refused route file and warns on a shadowed
one. It does no vault lookup or extension resolution.
Untrusted collectives
A route file whose scheme is an extension type pulled from a collective not in
trustedCollectives is refused alone. The error names the route, scheme and
collective and the fix, swamp extension trust add <collective>, followed by a
restart or swamp serve reload.
Team mode
When several serve nodes share a v3 datastore, only the leader takes runs. A follower that receives a delivery for a configured route passes it to the leader as it came, raw body and headers, after its size check and before it verifies the signature or runs any extension hook. The leader verifies the delivery with its own endpoint config and answers it.
Every node therefore needs the same webhook config: the follower needs the route
to accept the delivery, and the leader's secret and scheme decide it. A follower
that knows no leader address verifies the delivery itself, and refuses a valid
one with a retryable 503 and code serve_not_leader:
{
"error": "This serve node does not lead the datastore; try again",
"code": "serve_not_leader"
}The response carries Retry-After: 5. See
Run a Multi-Instance Deployment.
Related
- Serve Flags — full flag reference
for
swamp serve - Vaults — vault types, creation, and key management
- Extension Manifest — Webhooks — webhook extension handler interface