Friction
POST /api/workflows/<id>/webhook returns a 2xx body containing the captured executionId (or id — see #55), but no schema documents what else may appear in the response. Our adapter at crates/sbo3l-keeperhub-adapter/src/lib.rs:316-319 parses only executionId / id and discards the rest. We've observed (informally, across a handful of submissions) responses also containing:
status — sometimes "queued", sometimes "running", sometimes absentmetadata — sometimes a nested object, sometimes a flat key/value, sometimes absenterror — appears on partial-success delivery; no documented enumeration of possible values
Without a schema, every adapter author guesses at which fields are stable, which are nullable, which are optional. The result: brittle parsers + silent drops of useful response data.
Proposed fix
Publish a JSON Schema (Draft 2020-12) at /schemas/webhook-response.v1.json describing the canonical 2xx response envelope. Each field annotated with required / nullable / additionalProperties semantics. Sister to issue #48 (request-side schema).
Bonus: an OpenAPI 3.1 spec for the whole webhook surface (request + response) so adapter authors can codegen typed clients in any language.
Context
Filed as part of SBO3L's KeeperHub Builder Feedback round 3 for ETHGlobal Open Agents 2026. Sister: #48 (request schema), #56 (max payload size). Together: a complete documented contract.
Friction
POST /api/workflows/<id>/webhookreturns a 2xx body containing the capturedexecutionId(orid— see #55), but no schema documents what else may appear in the response. Our adapter atcrates/sbo3l-keeperhub-adapter/src/lib.rs:316-319parses onlyexecutionId/idand discards the rest. We've observed (informally, across a handful of submissions) responses also containing:status— sometimes"queued", sometimes"running", sometimes absentmetadata— sometimes a nested object, sometimes a flat key/value, sometimes absenterror— appears on partial-success delivery; no documented enumeration of possible valuesWithout a schema, every adapter author guesses at which fields are stable, which are nullable, which are optional. The result: brittle parsers + silent drops of useful response data.
Proposed fix
Publish a JSON Schema (Draft 2020-12) at
/schemas/webhook-response.v1.jsondescribing the canonical 2xx response envelope. Each field annotated withrequired/nullable/additionalPropertiessemantics. Sister to issue #48 (request-side schema).Bonus: an OpenAPI 3.1 spec for the whole webhook surface (request + response) so adapter authors can codegen typed clients in any language.
Context
Filed as part of SBO3L's KeeperHub Builder Feedback round 3 for ETHGlobal Open Agents 2026. Sister: #48 (request schema), #56 (max payload size). Together: a complete documented contract.