SET UP WEBHOOKS
Prerequisites: Swamp installed, a repository with a workflow, familiarity
with swamp serve. See swamp serve how-to guides
for server setup.
Start the server with a GitHub webhook
The --webhook flag registers an HTTP endpoint that triggers a workflow when it
receives a POST request. The format is
<route>:<workflow>:<secret>[:<scheme>[:<header>[:<prefix>]]].
swamp serve --webhook '/hooks/github:deploy-pipeline:mysecret'The server validates the request signature using the X-Hub-Signature-256
header (HMAC-SHA256) before triggering the workflow.
Put new routes under /hooks/, with every segment made of letters, digits and
- . _ ~: a route like that can later move into a reviewed
route file without changing the URL
configured at the sender.
Test locally with curl
Compute the HMAC signature and send a test request:
SECRET="mysecret"
BODY='{"ref":"refs/heads/main"}'
SIG=$(echo -n "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print "sha256="$2}')
curl -X POST http://localhost:9090/hooks/github \
-H "Content-Type: application/json" \
-H "X-Hub-Signature-256: $SIG" \
-d "$BODY"Use an environment variable for the secret
To avoid putting secrets in command arguments:
swamp serve --webhook '/hooks/github:deploy-pipeline:@env=WEBHOOK_SECRET'Use a file-based secret
swamp serve --webhook '/hooks/github:deploy-pipeline:@file=/run/secrets/webhook'Use a vault-managed secret
Store the secret in a vault, then reference it with @vault=<name>:<key>:
swamp serve --webhook '/hooks/github:deploy-pipeline:@vault=prod-secrets:webhook-key'Any configured vault backend works. See the vaults reference for vault setup and the secret source explanation for when to choose vaults over environment variables or files.
Add a route through a route file
A route file adds a webhook route through a reviewed change to the repository
instead of a serve flag or serve.yaml edit. Approving the file in review
approves its workflow, scheme and secret reference. Its runs are authorized as
service:webhook, like any other route.
1. Store the secret in a vault
A route file accepts only a @vault=<vault>:<key> secret. A literal, @env= or
@file= secret refuses the file.
swamp vault put prod-secrets webhook-key2. Write the route file
Create one YAML file per route at the top level of webhook-routes/ in the
repository:
# webhook-routes/github.yaml
route: /hooks/github
workflow: deploy-pipeline
secret: "@vault=prod-secrets:webhook-key"
scheme: githubA route file takes the same fields as a serve.yaml webhook entry: route,
workflow, secret, scheme, header, prefix and config. Any other key
refuses the file. Serve reads only *.yaml and *.yml files directly inside
the directory, not subdirectories.
The route must sit under /hooks/ and name a path below it. Each segment must
be non-empty, must not be . or .., and may contain only letters, digits and
- . _ ~.
The file must be a regular file of at most 64 KiB, with no YAML anchors or aliases and no nesting deeper than 32 levels. A symlink is followed only when its target stays inside the directory. Two files that claim the same route are both refused.
To read route files from another directory, start serve with
--webhook-routes-dir <path> (webhook-routes-dir in the serve config,
SWAMP_WEBHOOK_ROUTES_DIR). A relative path resolves against the repository.
The directory may not be, or sit inside, extensions/, the repository's webhook
extensions directory or .swamp/; serve then loads no route files and still
starts.
3. Check the files
swamp serve check-configWith a directory holding one good file and ten bad ones, each refused file is listed with the reason, and the command exits non-zero:
Auth mode: none
No usernames to resolve in this mode.
Webhook route file errors:
✗ Refused webhook route file badchar.yaml (route /hooks/git hub): the route has segment 'git hub' with characters other than letters, digits and '-', '.', '_', '~'
✗ Refused webhook route file bare.yaml (route /hooks/): the route is the bare /hooks/ prefix; name a route under it
✗ Refused webhook route file dot.yaml (route /hooks/a/../b): the route has a '.' or '..' segment, which no request path can match
✗ Refused webhook route file empty.yaml (route /hooks/a//b): the route has an empty segment
✗ Refused webhook route file envsec.yaml (route /hooks/env): the secret must be a vault reference (@vault=<vault>:<key>); route files refuse literal, @env= and @file= secrets
✗ Refused webhook route file literal.yaml (route /hooks/lit): the secret must be a vault reference (@vault=<vault>:<key>); route files refuse literal, @env= and @file= secrets
✗ Refused webhook route file outside.yaml (route /ci/github): the route is not under /hooks/, which route files require
✗ Refused webhook route file unknown.yaml (route /hooks/x): unknown key 'foo'; a route file takes route, workflow, secret, scheme, header, prefix, config
✗ Refused webhook route file dup1.yaml (route /hooks/dup): dup2.yaml also claims this route; each route belongs to one file
✗ Refused webhook route file dup2.yaml (route /hooks/dup): dup1.yaml also claims this route; each route belongs to one file
Grant files: 0 file(s) checked, no problems
Result: FAILED (10 webhook route file(s) refused; swamp serve would start without them)check-config does not read vaults or resolve extension schemes, so a missing
vault key or an uninstalled scheme is refused only by serve.
A refused file refuses only its own route. Serve reports it at startup, on
reload and in check-config, and starts and serves the other routes.
4. Apply the route
Merge the change, deploy it to the serve host, then reload:
swamp serve reloadTo apply route files without a reload, start serve with
--webhook-routes-poll <duration> (for example 30s; minimum 1s, default
off). Serve checks the directory at that interval and applies a change once two
checks see the same files. The poll interval is read at startup, and a poll
changes only route-file routes.
To remove a route, delete its file. The route goes on the next reload or poll.
When an edit or a vault fails
- On a reload or poll, an edit that stops a file loading keeps that file's last good route serving, and the reload reports the error.
- If a vault cannot answer during a reload, an unchanged file keeps its live route. A missing key, a refused read or an edited file still drops the route. At startup, a vault outage refuses the file.
- An extension scheme pulled from a collective that is not in
trustedCollectivesrefuses the file. Trust the collective withswamp extension trust add <collective>, then reload.
When a serve route uses the same path
A serve.yaml or --webhook route on the same path wins. check-config and
serve report the route file as shadowed. For a route file good.yaml on
/hooks/github:
Webhook warnings:
! Shadowed webhook route file good.yaml (route /hooks/github): the serve config defines the same route, which serve uses insteadExtensions cannot register routes; only serve.yaml, --webhook and route
files can.
Set up a Linear webhook
Use the linear scheme. Linear sends a signature in the Linear-Signature
header:
swamp serve --webhook '/hooks/linear:triage-workflow:@env=LINEAR_SECRET:linear'Set up a Stripe webhook
Use the stripe scheme. Stripe uses the Stripe-Signature header with
timestamp-based signatures:
swamp serve --webhook '/hooks/stripe:billing-workflow:@env=STRIPE_WEBHOOK_SECRET:stripe'Set up a Jira webhook
Use the jira scheme. Jira sends a signature in the X-Hub-Signature header
with a sha256= prefix:
swamp serve --webhook '/hooks/jira:on-issue:@env=JIRA_WEBHOOK_SECRET:jira'Set up a generic webhook
For services that send a static token in a custom header, use the generic
scheme. Specify the header name and optional value prefix:
swamp serve --webhook '/hooks/custom:my-workflow:mytoken:generic:X-Api-Key'If the service sends the token with a prefix (e.g., Bearer mytoken):
swamp serve --webhook '/hooks/custom:my-workflow:mytoken:generic:Authorization:Bearer 'Access webhook payload in workflow CEL
Map payload fields to workflow inputs in the workflow's trigger.inputs, then
read them in steps as inputs.<name>. The webhook namespace exists only while
trigger.inputs is evaluated:
webhook.body— parsed JSON body, or the raw string for a non-JSON payloadwebhook.headers— request headers, with lowercased nameswebhook.route— the matched route
trigger:
inputs:
ref: "${{ webhook.body.ref }}"
event: '${{ webhook.headers["x-github-event"] }}'
inputs:
type: object
properties:
ref: { type: string }
event: { type: string }
required: [ref]A step reads ${{ inputs.ref }}. A webhook.* reference in a step input or a
guard fails with Unknown variable: webhook.
A valid signature proves who sent the request, not that its fields are safe: a
pull request title or branch name is set by whoever opens the pull request.
Payload fields mapped to workflow inputs through trigger.inputs are data. When
a command/shell step splices one into run, it reaches the shell as one
literal word through an environment variable reference, never as shell syntax.
See
Data Values in Shell Commands.
Correlate webhook-triggered runs with your traces
Webhook requests automatically propagate W3C traceparent and tracestate
headers into the triggered workflow execution. Include these headers in your
webhook request to make the swamp run appear as a child span of your trace:
curl -X POST http://localhost:9090/hooks/github \
-H "Content-Type: application/json" \
-H "X-Hub-Signature-256: $SIG" \
-H "traceparent: 00-abcd1234abcd1234abcd1234abcd1234-abcd1234abcd1234-01" \
-d "$BODY"No additional configuration is needed on the swamp serve side.
Receive Telegram bot updates
Use the @swamp/telegram extension scheme to receive Telegram bot updates.
Telegram uses a static secret token in the X-Telegram-Bot-Api-Secret-Token
header — weaker than HMAC, so TLS is required.
1. Configure serve.yaml
webhooks:
- route: /hooks/telegram
workflow: on-telegram
secret: "@env=TELEGRAM_BOT_SECRET"
scheme: "@swamp/telegram"2. Register the webhook with Telegram
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"The secret_token must match the secret configured in serve.yaml. Telegram
sends it back in every update request for the server to verify.
3. Access the update in your workflow
Map the chat id and text in the workflow's trigger.inputs, then read them as
inputs in the step:
trigger:
inputs:
chatId: "${{ webhook.body.message.chat.id }}"
text: "${{ webhook.body.message.text }}"
inputs:
type: object
properties:
chatId: { type: integer }
text: { type: string }
required: [chatId, text]
jobs:
- name: main
steps:
- name: handle-message
task:
type: behavior
behavior: telegram-handler
methodName: process
inputs:
chatId: "${{ inputs.chatId }}"
text: "${{ inputs.text }}"Security caveats
- The secret is transmitted in the clear as a header value, not derived from the request body. Always serve over HTTPS.
- The handler uses constant-time comparison to prevent timing attacks.
- Do not use
@swamp/telegramover plain HTTP — any intermediary can read the secret.
Use an extension webhook scheme
Extension webhook schemes (@collective/name) provide custom verification logic
for services not covered by the built-in schemes. Extensions are auto-pulled
from trusted collectives on first reference.
If swamp serve cannot resolve a scheme that a trusted collective publishes,
ask the extension's author to push a new version with swamp extension push:
the registry finds a scheme only in a version that lists it.
webhooks:
- route: /hooks/custom
workflow: on-custom-event
secret: "@env=CUSTOM_SECRET"
scheme: "@acme/my-webhook"
config:
challengeField: challengeThe config object is passed to the extension handler. See the
webhooks reference
for the handler lifecycle and the
manifest reference for how to
author a webhook extension.
For the full --webhook flag specification, run swamp help serve.