Skip to main content

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-bot

The 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

  1. The server resolves the extension scheme and calls createHandler(config).
  2. On each incoming request, verify(body, headers, secret) runs first. A false return or a thrown error responds 401. Verification is fail-closed: any error rejects the request.
  3. Hooks fire only after successful verification — a failed verify never triggers hooks.
  4. If transform(body, redactedHeaders) is defined, the transformed payload replaces the raw body for downstream processing.
  5. If respond(payload) is defined, its return value ({ status, headers?, body?, enqueue }) controls the HTTP response and whether the workflow run is enqueued. Without respond, 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 instead

swamp 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.