Friction
A KeeperHub workflow's behavior can change over time — its author edits the steps, swaps integrations, tightens validation. Adapter callers (SBO3L's KH adapter, Devendra's langchain-keeperhub, anyone integrating downstream) have no way to:
- Pin against a specific workflow revision
- Detect that a workflow they were calling has changed shape
- Cleanly roll back to a previous workflow version when a new one breaks
Today the only <id> in the webhook URL is the workflow's identity — not its revision. Submitting against a workflow that silently changed its required envelope shape produces opaque 422s with no way to say "use the version I've actually integration-tested against."
Proposed fix
Two additions:
-
Stable per-revision IDs. When a workflow is edited, KH retains the prior revision and exposes it at /api/workflows/<id>@<revision>/webhook. The bare /api/workflows/<id>/webhook continues to mean "latest" with explicit fall-through documentation.
-
Back-compat policy. Document KH's commitment to revision longevity (e.g. "older revisions remain reachable for 90 days post-supersede; webhook responses for retired revisions return 410 Gone with the migration URL"). Adapter authors then know how to size their pinning + alerting infrastructure.
Context
Filed as part of SBO3L's KeeperHub Builder Feedback round 3 for ETHGlobal Open Agents 2026. Composes with #55 (X-KeeperHub-Schema-Version header) — workflow revision is the orthogonal axis.
Friction
A KeeperHub workflow's behavior can change over time — its author edits the steps, swaps integrations, tightens validation. Adapter callers (SBO3L's KH adapter, Devendra's
langchain-keeperhub, anyone integrating downstream) have no way to:Today the only
<id>in the webhook URL is the workflow's identity — not its revision. Submitting against a workflow that silently changed its required envelope shape produces opaque 422s with no way to say "use the version I've actually integration-tested against."Proposed fix
Two additions:
Stable per-revision IDs. When a workflow is edited, KH retains the prior revision and exposes it at
/api/workflows/<id>@<revision>/webhook. The bare/api/workflows/<id>/webhookcontinues to mean "latest" with explicit fall-through documentation.Back-compat policy. Document KH's commitment to revision longevity (e.g. "older revisions remain reachable for 90 days post-supersede; webhook responses for retired revisions return
410 Gonewith the migration URL"). Adapter authors then know how to size their pinning + alerting infrastructure.Context
Filed as part of SBO3L's KeeperHub Builder Feedback round 3 for ETHGlobal Open Agents 2026. Composes with #55 (
X-KeeperHub-Schema-Versionheader) — workflow revision is the orthogonal axis.