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.

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'

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

Inside a workflow step, the webhook payload is available through CEL expressions:

webhook.headers — request headers
webhook.body — parsed JSON body
webhook.params — URL query parameters

For the full --webhook flag specification, run swamp help serve.