Skip to main content

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

2. 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: github

A 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-config

With 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 reload

To 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 trustedCollectives refuses the file. Trust the collective with swamp 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 instead

Extensions 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 payload
  • webhook.headers — request headers, with lowercased names
  • webhook.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/telegram over 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: challenge

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