[docs] Publish JSON Schema for webhook 2xx response envelope

[B2JK-Industry]

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 absent
• metadata — sometimes a nested object, sometimes a flat key/value, sometimes absent
• error — 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.

[suisuss]

Verified against the live serializer (KeeperHub/keeperhub, staging branch, app/api/workflows/[workflowId]/webhook/route.ts) - the reason and scope hold. docs/api/workflows.md's "Webhook Trigger" section documents the endpoint and its auth requirement only, no response body at all, and there is no JSON Schema or OpenAPI spec published anywhere in either repo. This is a real, unaddressed gap.

The plan needs to change though - both what the schema should say, and where it should live.

Actual response shape (confirmed from the live handler, not guessed):

The success path (200) returns exactly two fields:
{ "executionId": "<execution row id>", "status": "running" }
(the NextResponse.json({ executionId: execution.id, status: "running" }, ...) call at the end of POST in that file.) status is a fixed literal here - it is never "queued" and never omitted on this endpoint; only "running" is ever written into a fresh success response.

One more field can appear, which you did not mention and is worth documenting: when the caller sends an Idempotency-Key header and this response is a replay of an already-completed request, lib/idempotency.ts's annotateReplay() adds "idempotentReplay": true to the stored body before it is returned. So the complete field set for the 2xx envelope is:

Field	Type	Presence
executionId	string	always
status	string, literal "running"	always
idempotentReplay	boolean, literal true	only on a replayed idempotent response

I could not find metadata anywhere in this handler or the idempotency path, on any status code. I also could not find a case where this endpoint returns error on a 2xx response - error only shows up on the non-2xx failure branches (400/401/403/404/410/429/402/500), which are outside a "2xx envelope" schema by definition. If you are seeing metadata or error on a 2xx response in production, that is a separate and more urgent bug (code and deployed behavior disagreeing) - please reopen with a raw response dump if so, because nothing in the current handler produces that.

Side note on #55: this handler only ever emits executionId, never id, on the current success path. I do not see the executionId/id split here in the current code. Might already be resolved, might be a different endpoint or an older deploy you observed. Not resolving #55 here, just flagging what I found while I was in the file.

Where this should be published: this repo (cli) does not have a natural home for a served schema file - its docs/ directory is auto-generated kh command reference (docs/generate.go/docs/doc.go), not API documentation, and there is no /schemas route or static-serving setup here, and no webhook command that would consume this schema. The actual API reference for this endpoint lives in KeeperHub/keeperhub's docs/api/workflows.md, and that is also the repo that would need to serve a schema file at a URL. Worth deciding whether this issue tracks the work here with the PR landing in keeperhub, or gets filed/transferred there directly - happy to do either, but wanted to flag it rather than accept a plan that cannot be implemented in this repo's code.

Scope: keeping this to the response schema for POST /api/workflows/{id}/webhook only. The "Bonus: OpenAPI 3.1 for the whole webhook surface" does not need to land with this - per this repo's own "should this be one change" test, the response schema can ship correct and complete with the OpenAPI spec absent or reverted. If you still want the OpenAPI spec, please file it separately so it can be scoped and accepted on its own merits.

Accepting on this basis: publish a JSON Schema for the three-field envelope above (executionId, status, idempotentReplay), scoped to this one endpoint, with the understanding that implementation likely happens against KeeperHub/keeperhub rather than this repo.