Skip to main content
← Back to list
01Issue
BugShippedSwamp ClubPublic
AssigneesNone

Relationships

↔ sibling #4556

#4533 Docs: webhook payload is only in scope in trigger.inputs; document run id header and route reload

Opened by stack72 · 11/8/2026· Shipped 11/10/2026

What is wrong

The manual contradicts itself on where webhook payload data is available, and it misses changes from swamp-club#3434.

  1. The workflows reference says no inputs come from the payload.
    • content/manual/reference/workflows.md, around lines 158-160 and 557, says a webhook run "extracts no inputs from its payload (the body is used only for signature verification)".
    • In fact trigger.inputs is evaluated against the payload, so ${{ webhook.body.* }}, webhook.headers and webhook.route map payload fields to workflow inputs. Code: src/serve/deps.ts, the TriggerInputResolver call.
  2. The how-to and the webhooks reference say webhook.* works anywhere in the workflow.
    • content/manual/how-to/set-up-webhooks.md, step 3 of the Telegram section, uses ${{ webhook.body.message.chat.id }} directly in step inputs.
    • content/manual/reference/swamp-serve/webhooks.md, "CEL context", says the namespace "is available in CEL expressions within that workflow".
    • In fact webhook.* is in scope only inside trigger.inputs. In step inputs or a guard it fails with Unknown variable: webhook. The working pattern is to map the field in trigger.inputs and read inputs.<name> in the step.
  3. New in swamp-club#3434, not yet documented:
    • Every queued webhook response carries the run id in an X-Swamp-Run-Id header. That includes extension respond replies that also enqueue. The JSON body is unchanged.
    • A replayed delivery keeps the same run id. A refused run has no record, and its webhook_denied event and audit entry name the id.
    • swamp serve reload can add the first webhook route to a serve that started with none.
    • Routes from --webhook flags are fixed until restart. Reload warns when the config file also lists webhooks.
    • The dashboard Webhooks page and the admin health snapshot show each route's source (config or flag).

Suggested changes

  • In the workflows reference, replace the "no inputs are extracted" wording with a trigger.inputs example that maps webhook.body fields, and say this is the only place the namespace exists.
  • Rewrite the Telegram step 3 to map chatId and text in trigger.inputs and read inputs.chatId and inputs.text in the step.
  • In the webhooks reference, scope the "CEL context" section to trigger.inputs. Add the X-Swamp-Run-Id header to the response table, and a short note on reloading routes (file list reloads, flags do not).
02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS✓SHIPPEDLINKED+ 3 MOREPR_LINKED+ 1 MORESESSION_SUMMARIZED

Shipped

11/10/2026, 7:10:29 AM

Click a lifecycle step above to view its details.

03Sludge Pulse
stack72 linked sibling of #455611/9/2026, 11:33:51 PM
Editable. Press Enter to edit.

system commented 11/8/2026, 11:54:59 PM

Classified automatically when this issue was filed.

  • Type: Bug

If you feel this classification is incorrect, add a ripple to tell us so.

Sign in to post a ripple.