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

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.

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