Repository navigation
fix(order)!: cover webhook-id and webhook-timestamp in the signing gate - #659
Conversation
d05b53d to
f6f69b4
Compare
|
@gsmith85 flagging as a requested reviewer. This signs |
f6f69b4 to
1968490
Compare
|
Thanks for catching this, @vishkaty. Moving A few adjustments to make this land cleanly across the spec:
|
… signing gate Addresses the review on Universal-Commerce-Protocol#659. Moving event_id and created_time into Webhook-Id and Webhook-Timestamp in Universal-Commerce-Protocol#342 left them outside Content-Digest, so an order webhook's identity and freshness were unsigned. The first draft fixed that with a rule local to order/index.md. Per review, the rule belongs in the global covered-component gate instead, so one route-agnostic verifier handles REST requests and webhooks without endpoint branching. 1. overview/index.md IRA step 5 and signatures.md now carry webhook-id and webhook-timestamp in the closed sign-if-present set: a table row each, a footnote giving the reason, and both the sign_rest_request and verify_rest_request pseudocode. rest.openapi.json already marks both headers required: true on order_event_webhook, so the presence gate does the rest. 2. Webhook-Id deduplication is SHOULD, not MUST. An order webhook carries the full current state rather than a delta, and Webhook-Timestamp is now signed and immutable, so a platform applying highest-timestamp-wins, or reconciling through GET /orders/{id}, is already replay-safe without keeping delivery state. Deduplication still earns its place for retry short-circuiting and same-second events, which is a SHOULD. 3. Signing step 2 and Verification step 6 reference REST Request Signing and REST Request Verification rather than listing components, which had read as if @method, @authority, @path, @query and content-type were optional. 4. The example Signature value matches Universal-Commerce-Protocol#590's form, and the playground.md comment points at shopping/order/index.md. BREAKING CHANGE: a signature covering only the baseline REST components is no longer valid for a delivery carrying Webhook-Id or Webhook-Timestamp. Businesses must add both to Signature-Input; platforms must reject deliveries that omit them. The headers are already required: true on the webhook operation, so this binds signatures to headers the delivery was already obliged to carry. Verified on this branch, rebased onto main b0e81ad: validate_examples 376 passed 0 failed; its unit tests 59 passed; ucp-schema lint 144 files all passed; DOCS_MODE=spec mkdocs build --strict exit 0 with 0 warnings, 102 pages and 52 social cards; check_links byte-identical to the control on unmodified main, the same three pre-existing missing anchors under documentation/, none in the files touched here. Both newly referenced anchors resolve in the built site.
1968490 to
b65f4a1
Compare
Moving event_id and created_time into Webhook-Id and Webhook-Timestamp in Universal-Commerce-Protocol#342 left them outside Content-Digest, so the identity and the freshness of an order event travelled unsigned. Per review on Universal-Commerce-Protocol#659 the rule belongs in the global covered component gate rather than in order/index.md, so one route agnostic verifier handles REST requests and webhooks with no endpoint branching. Both headers join the closed sign if present set in overview/index.md IRA step 5 and in signatures.md, as a row each in the Signed Components table with a footnote giving the reason, plus sign_rest_request and verify_rest_request. rest.openapi.json already marks both required: true on order_event_webhook, and they appear on no other operation in any of the four service documents, so the header presence gate does the rest. Deduplication on Webhook-Id is SHOULD rather than MUST. An order webhook carries the full current state of the order rather than a delta, which the order page states at three points, so a platform applying deliveries in Webhook-Timestamp order, or reconciling through GET /orders/{id}, converges without per delivery state. Deduplication still earns a SHOULD for retry short circuiting and for events that share a timestamp, whose resolution is one second. Signing step 2 and Verification step 6 reference REST Request Signing and REST Request Verification instead of naming a subset of components, which had read as if @method, @authority, @path, @query and content-type were optional. The example Signature value takes the Universal-Commerce-Protocol#590 form, and the playground.md comment points at shopping/order/index.md. The Signed Components table is re-padded because the webhook-timestamp row is wider than the previous column width, which trips markdownlint MD060 under the version super-linter pins. BREAKING CHANGE: a signature covering only the baseline REST components is no longer valid for a delivery carrying Webhook-Id or Webhook-Timestamp. Businesses must add both to Signature-Input, and platforms must reject deliveries that omit them. Both headers are already required: true on order_event_webhook, so this binds signatures to headers the delivery was obliged to carry, and the blast radius is the order event webhook alone.
b65f4a1 to
ddbedfa
Compare
|
Thanks for the detailed review. All five are done, rebased onto
Two things worth flagging. The Signed Components table is re-padded, so it shows more changed lines than the two new On the pseudocode, I deliberately kept this to the webhook lines. Two findings of the same class that I left out, both in the description with reasoning: Verification is in the description. The four statements of the gate are checked mechanically: |
gsmith85
left a comment
There was a problem hiding this comment.
Thanks for the clean update and thorough sweep, @vishkaty. Everything from the review is addressed nicely, so this is good to go from my side.
On the follow-ups you flagged:
Request-Id: Leaving it out of the covered-component gate is intentional, since it is a correlation and tracing header rather than a security or replay signal, so we don't need an issue there.- Remaining DER signature examples (
lodging/booking/rest.md:1590andlodging/booking/mcp.md:1072): Good catch that #590 missed the lodging tree. A separate small PR to clean those two up would be welcome. - Standard Webhooks timestamp note (
order/index.md:688): Agreed that this is worth clarifying. Because UCP usesWebhook-Timestampas the immutable event occurrence time so platforms can order full-state snapshots across retries, calling out that divergence from Standard Webhooks' per-attempt delivery timestamp (and noting that platforms shouldn't apply a narrow wall-clock freshness window to delayed retries) would be a helpful separate PR or issue.
|
Thanks for the approval, and for picking up the two follow ups. A correction to my own note first, because you relied on it. I wrote that the The two beginning Second correction, to the history rather than the count: #590 did not miss the #934 now carries all four, using the same truncated placeholder #590 The fifth DER value is Two further things turned up while checking, both outside either PR and both The published
Happy to open either, or neither. |
igrigorik
left a comment
There was a problem hiding this comment.
A few nits and suggestions, otherwise I think this is good to land -- ty for the fix!
Review feedback from @igrigorik on Universal-Commerce-Protocol#659, applied as suggested. `Webhook-Id` identifies the event, not the delivery: it is identical on every retry, which is what makes the SHOULD-deduplicate rule work. `source/services/shopping/rest.openapi.json` calls it "The unique identifier of a webhook event" and `order/index.md:697` already said "Unique event identifier", so the covered-components table was the only place calling it a delivery identifier. The `****` footnote said `Idempotency-Key` is "Required for POST, PUT, DELETE, PATCH" two lines above a note saying webhook deliveries carry none, in the same table. IRA step 5 treats it as sign-if-present and carries the parenthetical that whether a request must carry the header at all is a binding-level rule, separate from the coverage check. The footnote now says that. The `‡` note described `Webhook-Timestamp` as a freshness value, which is the Standard Webhooks meaning: attempt time, re-stamped on retry, checked against a tolerance window. The UCP value is the immutable event time, so the note now says event identity and event time, and both headers are per-event rather than per-delivery. `order/index.md:748` said the verification section requires rejecting "a delivery that omits either". That section is sign-if-present and says nothing about absent headers; the absent case is `required: true` in the OpenAPI binding. The rule it does define is: header present, signature does not cover it, treat as unsigned. The text now says that. Swept each point across docs/specification, and across source/, scripts/ and the scaffolds, rather than editing the four cited lines. Line numbers below are as at the parent of this commit. Out of class and left alone, with reasons: `:754` per-delivery state means state held about each delivery; `:376` and `:868` use freshness for the WBA created/expires window, which is a freshness signal; `:452` already uses the signature-side framing; `:824` describes the replay-protection mechanism. `:436` "Idempotency header (state-changing)" is the one debatable exclusion: it keeps the method framing one column left of the footnote this commit corrects, and the column mixes conditions with descriptions, so it is raised on the PR rather than changed here. Gates: validate_examples 398 passed, 0 failed, 0 errors, 53 skipped, identical to the control; its unit tests 59 passed; ucp-schema lint source/ 145 files all passed; pre-commit on the changed files all Passed; markdownlint 0.47.0 and 0.49.0 both clean, and a planted table misalignment reds MD060 on 0.49.0.
|
Thanks for the review. All four suggestions applied as written in 96d81f1, I swept the same vocabulary across One judgment call I left to you. The Description cell for that row still reads Correcting something I wrote earlier in this thread. I said |
igrigorik
left a comment
There was a problem hiding this comment.
👍 and ty for iterating on this!
PTAL, one more suggestion before we land.
…stamp Review feedback from @igrigorik on Universal-Commerce-Protocol#659, applied as suggested. The platform-side rule said platforms SHOULD deduplicate on Webhook-Id and may apply deliveries in Webhook-Timestamp order. Both depend on a retry carrying the same two values, and nothing in the spec obliged a business to do that, so the guarantee rested on an assumption. Businesses MUST now send retries with the original Webhook-Id and Webhook-Timestamp, stated once in the Events prose and once in the Business guidelines next to the retry MUST it completes. The header table row for Webhook-Id reads "Event identifier; stable across retries", which is the same fact where a reader meets the header first. Swept the class: shopping/order is the only capability with a webhook retry rule today, so no sibling needs the same obligation. Left alone: the Webhook-Id parameter in source/services/shopping/rest.openapi.json reads "The unique identifier of a webhook event", which is consistent with stability across retries without stating it. That belongs in the separate follow-up @gsmith85 invited rather than in an approved PR. Gates: markdownlint 0.49.0, the version super-linter pins and the one that carries MD060, is clean, and the new Webhook-Id row keeps the header table at 70 characters. validate_examples 398 passed 0 failed 0 errors 53 skipped, test_validate_examples 66 passed, ucp-schema lint source/ 145 files all passed, test_schema_tables rc 0, each identical to main d9c18e0. None of those four can observe a prose edit in docs/, so they show the change breaks nothing rather than that it is right; the table width check is the one that earns its place, because the row came from the suggestion UI, which is how MD060 bit this branch before.
|
All three applied as written in bee1cf5, on top of your merge of Agreed on the producer half: the dedup and ordering SHOULD rested on retries carrying One note for the queue: #938 touches the same lines in markdownlint 0.49.0 is clean, and the new |
What this changes
#342 moved
event_idandcreated_timeout of the order webhook body and intoWebhook-IdandWebhook-Timestamp. Those headers sit outsideContent-Digest, so theidentity and the freshness of an order event became unsigned: a delivery could be replayed
with an altered
Webhook-IdorWebhook-Timestampand still verify.Revised per review, so the rule lives in the global covered component gate rather than in
order/index.md.webhook-idandwebhook-timestampjoin the closed sign if present set inoverview/index.mdIRA step 5 and insignatures.md: one row each in the SignedComponents table, a footnote giving the reason, and both pseudocode paths,
sign_rest_requestandverify_rest_request.rest.openapi.jsonalready marks bothrequired: trueonorder_event_webhook, so one route agnostic verifier now coversREST requests and webhooks with no endpoint branching.
Webhook-Iddeduplication is SHOULD, not MUST. An order webhook carries thefull current state of the order rather than a delta, which the order page states at
:554,:676and:833, so a platform applying deliveries inWebhook-Timestamporder, or reconciling through
GET /orders/{id}, converges without per delivery state.Deduplication keeps a SHOULD for retry short circuiting and for events that share a
timestamp, since the value has one second resolution.
Signing step 2 and Verification step 6 now reference REST Request Signing and REST
Request Verification instead of listing components, which had read as if
@method,@authority,@path,@queryandcontent-typewere optional.The example
Signaturevalue uses the docs(signatures): make example signature values raw r||s as the spec requires #590 form, and theplayground.mdcomment pointsat
shopping/order/index.md.The Signed Components table is re-padded in the same commit because the
webhook-timestamprow is wider than the previous first column width, which fails markdownlint MD060 under the
version super-linter pins. Details in the verification section.
Relationship to #785
sign_rest_requestonmainbranches onucp_agentwithout declaring it, passes noucp-agentvalue tobuild_signature_base, never appendssignature-agent, and brancheson an undeclared
bodywhere the parameter isbody_bytes. Those are all pre-existing, andopen PR #785 already fixes them, including the
signature-agent;key="<label>"form that WBAInterop item 3 requires. This PR does not touch any of that and does not duplicate it: the
only additions here are
webhook_idandwebhook_timestampas parameters, their twocomponents.appendlines, and their two entries in theheadersmap.The two PRs do touch adjacent lines of the same block, so they conflict textually
(
git merge-treereports a conflict in the signature line and the component list). Theconflict is two declarations in one parameter list and two lines in one
ifsequence, sowhichever lands first, rebasing the other is mechanical. Happy to rebase on top of #785 if
you would rather take that one first.
BREAKING CHANGE
A signature covering only the baseline REST components is no longer valid for a delivery
that carries
Webhook-IdorWebhook-Timestamp. Businesses must add both toSignature-Input; platforms must reject deliveries that omit them.Justification: both headers are already
required: trueonorder_event_webhook, so thisbinds signatures to headers the delivery was obliged to carry anyway. Leaving them uncovered
means the replay signal introduced by #342 is unauthenticated, which is a security property
rather than a style question. The blast radius is the order event webhook alone: a sweep of
all four service documents under
source/services/findswebhook-idandwebhook-timestampon exactly one operation,order_event_webhook.Class sweep
The class is every statement of the covered component gate that has to agree, plus any
header obliged on the wire but absent from the gate. The second leg was swept across all
four OpenAPI documents, not only the shopping one.
overview/index.mdIRA step 5 closed setsignatures.mdSigned Components tablesignatures.mdsign_rest_requestsignatures.mdverify_rest_requestorder/index.mdprose, signing step 2, verification step 6playground.mdpayload and comment pathucp_agent,signature_agentandbodyinsign_rest_requestrequest-id,required: trueon 20 operationslodging/booking/mcp.mdandrest.mdRequest-Idisrequired: trueon 20 operations, 13 in shopping, 5 in lodging and 2 incommon, and appears in no covered component gate, so by the same reasoning it travels
obliged and unsigned. I am not proposing a rule for it here, because whether a tracing
identifier should be signed is a design question for you rather than a defect: the spec says
nothing about it either way, which is the part worth recording. Say if an issue would help.
The DER form value
:MEUCIQDTxNq8h7LGHpvVZQp1iHkFp9...:that item 4 replaced also appears atlodging/booking/rest.md:1590. Correcting what this paragraph claimed when it was written: it saidtwo values remained and that #590 had never reached the lodging tree. The count was wrong and
the history was misleading. Five DER values exist on main, at
lodging/booking/mcp.md:1072and:1100,lodging/booking/rest.md:1590and:1615, andshopping/order/index.md:752. Thecount came from grepping
MEUCI, which matches the two request signing values and misses thetwo response signing values whose base64 begins
MFQCI, so it found three of five. On thehistory, no file under
lodging/bookingexisted at the merge commit of #590 on 2026-07-24; thecapability arrived with #780 on 2026-09-24, carrying strings byte identical to the ones #590 had
already replaced in the shopping pages. #934 now replaces all four lodging values, and this PR
replaces the fifth at
shopping/order/index.md:752.One observation outside the scope of this change:
order/index.md:688says webhook headersfollow Standard Webhooks, while the header table and
rest.openapi.jsonboth defineWebhook-Timestampas the event occurrence time. Standard Webhooks defines its timestamp asthe time of the delivery attempt, updated on every retry. UCP looks right and the divergence is
pre-existing, but an implementer reading the Standard Webhooks reference would get retry
behaviour wrong. Happy to file that separately.
Verification
Run locally on this exact branch, rebased onto
mainb0e81ad, exit codes read directlyrather than through a pipe.
yamllint -c .github/linters/.yamllint.yml .ucp-schema lint source/source/changedvalidate_examples.py --schema-base source/schemas/test_validate_examples.py.cspell.json, the 4 changed files.github/linters/.markdownlint.json, the 4 changed filesDOCS_MODE=spec mkdocs build --strictcheck_links.pyon the composed siteTwo notes on how those were run, because the first attempt at each was misleading.
markdownlint has to be the version super-linter pins.
markdownlint-cli0.45.0 reports cleanhere because it predates MD060, which was added in markdownlint 0.39.0; super-linter 8.7.0
pins
markdownlint-cli ^0.49.0, and under 0.49.0 the first version of this branch failed withsignatures.md:438 MD060/table-column-style. Unmodifiedmainpasses. Re-padding the wholeSigned Components table clears it, which is why that table shows more changed lines than the
two added rows.
The
0 warningson the strict build is cache dependent on my machine, which has no libcairo,so the social plugin cannot render an uncached card. The branch has a warm card cache and
reports 0 warnings; a cold clone of unmodified
mainreports 52, all of them the samecairosvg failure. So that row is a real green for CI, which has cairo, but it is not a
differential between the two trees here.
scripts/build_local.sh --draft-onlyexits 1 on thismachine for the same reason, identically on
main. Neither tree produces a single non cairowarning. The root pass still writes its pages, so the artifact used for
check_linksis theshape CI assembles, root site plus merged spec versions.
ucp-schemalocally is 1.4.1, which is the current crates.io release and therefore whatsetup-build-envinstalls.Both anchors the order page newly references resolve in the built site,
id="rest-request-signing"and
id="rest-request-verification", linked three times each. Breaking one of them on purposetakes
check_linksfrom 0 to 1 naming the broken target, so that gate is not vacuous here.The four statements of the gate were checked mechanically rather than by eye. On unmodified
mainthe check reportswebhook-idandwebhook-timestampmissing from all four; on thisbranch it passes. Excising any one of the four edits alone puts it back to red, which is four
mutants for four edit sites.