Skip to content

fix(order)!: cover webhook-id and webhook-timestamp in the signing gate - #659

Merged
damaz91 merged 6 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/webhook-sign-standard-headers
Oct 16, 2026
Merged

damaz91 merged 6 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/webhook-sign-standard-headers

Conversation

@vishkaty

@vishkaty vishkaty commented Jul 31, 2026 •

Copy link
Copy Markdown
Contributor

What this changes

#342 moved event_id and created_time out of the order webhook body and into
Webhook-Id and Webhook-Timestamp. Those headers sit outside Content-Digest, so the
identity and the freshness of an order event became unsigned: a delivery could be replayed
with an altered Webhook-Id or Webhook-Timestamp and still verify.

Revised per review, so the rule lives in the global covered component gate rather than in
order/index.md.

  1. webhook-id and webhook-timestamp join the closed sign if present set in
    overview/index.md IRA step 5 and in signatures.md: one row each in the Signed
    Components table, a footnote giving the reason, and both pseudocode paths,
    sign_rest_request and verify_rest_request. rest.openapi.json already marks both
    required: true on order_event_webhook, so one route agnostic verifier now covers
    REST requests and webhooks with no endpoint branching.

  2. Webhook-Id deduplication is SHOULD, not MUST. An order webhook carries the
    full current state of the order rather than a delta, which the order page states at
    :554, :676 and :833, so a platform applying deliveries in Webhook-Timestamp
    order, 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.

  3. 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, @query and content-type were optional.

  4. The example Signature value uses the docs(signatures): make example signature values raw r||s as the spec requires #590 form, and the playground.md comment points
    at shopping/order/index.md.

The Signed Components table is re-padded in the same commit because the webhook-timestamp
row 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_request on main branches on ucp_agent without declaring it, passes no
ucp-agent value to build_signature_base, never appends signature-agent, and branches
on an undeclared body where the parameter is body_bytes. Those are all pre-existing, and
open PR #785 already fixes them, including the signature-agent;key="<label>" form that WBA
Interop item 3 requires. This PR does not touch any of that and does not duplicate it: the
only additions here are webhook_id and webhook_timestamp as parameters, their two
components.append lines, and their two entries in the headers map.

The two PRs do touch adjacent lines of the same block, so they conflict textually
(git merge-tree reports a conflict in the signature line and the component list). The
conflict is two declarations in one parameter list and two lines in one if sequence, so
whichever 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-Id or Webhook-Timestamp. Businesses must add both to
Signature-Input; platforms must reject deliveries that omit them.

Justification: both headers are already required: true on order_event_webhook, so this
binds 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/ finds webhook-id and
webhook-timestamp on 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.

Site Disposition
overview/index.md IRA step 5 closed set converted
signatures.md Signed Components table converted
signatures.md sign_rest_request converted, webhook lines only
signatures.md verify_rest_request converted
order/index.md prose, signing step 2, verification step 6 converted to reference the global sections
playground.md payload and comment path converted
ucp_agent, signature_agent and body in sign_rest_request pre-existing, open PR #785
request-id, required: true on 20 operations not converted, see below
DER form signature value, four sites in lodging/booking/mcp.md and rest.md not converted, taken by #934; see below

Request-Id is required: true on 20 operations, 13 in shopping, 5 in lodging and 2 in
common, 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 at
lodging/booking/rest.md:1590. Correcting what this paragraph claimed when it was written: it said
two 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:1072 and
:1100, lodging/booking/rest.md:1590 and :1615, and shopping/order/index.md:752. The
count came from grepping MEUCI, which matches the two request signing values and misses the
two response signing values whose base64 begins MFQCI, so it found three of five. On the
history, no file under lodging/booking existed at the merge commit of #590 on 2026-07-24; the
capability 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:688 says webhook headers
follow Standard Webhooks, while the header table and rest.openapi.json both define
Webhook-Timestamp as the event occurrence time. Standard Webhooks defines its timestamp as
the 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 main b0e81ad, exit codes read directly
rather than through a pipe.

Gate Result
yamllint -c .github/linters/.yamllint.yml . 0
ucp-schema lint source/ 0, 144 files all passed. CI skips this step: 0 files under source/ changed
validate_examples.py --schema-base source/schemas/ 0, 376 passed, 0 failed, 0 errors, 53 skipped
test_validate_examples.py 0, 59 passed, 0 failed
cspell, .cspell.json, the 4 changed files 0, no findings
markdownlint, .github/linters/.markdownlint.json, the 4 changed files 0
DOCS_MODE=spec mkdocs build --strict 0, 0 warnings, 102 pages
check_links.py on the composed site 0, all internal links validated, 110 pages

Two notes on how those were run, because the first attempt at each was misleading.

markdownlint has to be the version super-linter pins. markdownlint-cli 0.45.0 reports clean
here 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 with
signatures.md:438 MD060/table-column-style. Unmodified main passes. Re-padding the whole
Signed Components table clears it, which is why that table shows more changed lines than the
two added rows.

The 0 warnings on 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 main reports 52, all of them the same
cairosvg 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-only exits 1 on this
machine for the same reason, identically on main. Neither tree produces a single non cairo
warning. The root pass still writes its pages, so the artifact used for check_links is the
shape CI assembles, root site plus merged spec versions.

ucp-schema locally is 1.4.1, which is the current crates.io release and therefore what
setup-build-env installs.

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 purpose
takes check_links from 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
main the check reports webhook-id and webhook-timestamp missing from all four; on this
branch it passes. Excising any one of the four edits alone puts it back to red, which is four
mutants for four edit sites.

@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Jul 31, 2026
@vishkaty
vishkaty force-pushed the fix/webhook-sign-standard-headers branch from d05b53d to f6f69b4 Compare July 31, 2026 23:12
@vishkaty vishkaty changed the title docs(order): require webhook signatures to cover Webhook-Id and Webhook-Timestamp docs(order): sign Webhook-Id, Webhook-Timestamp, and UCP-Agent in the webhook signature Jul 31, 2026
@damaz91 damaz91 added bug Something isn't working documentation Improvements or additions to documentation status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 3, 2026
@damaz91
damaz91 requested review from alexpark20 and gsmith85 August 3, 2026 07:51
@vishkaty

Copy link
Copy Markdown
Contributor Author

@gsmith85 flagging as a requested reviewer. This signs Webhook-Id, Webhook-Timestamp, and UCP-Agent so the replay signal is covered by the signature. Happy to iterate.

@vishkaty
vishkaty force-pushed the fix/webhook-sign-standard-headers branch from f6f69b4 to 1968490 Compare August 24, 2026 03:38
@damaz91 damaz91 added status:stale-review Applied if a PR is waiting on a reviewer for too long and removed status:under-review labels Sep 3, 2026
@damaz91
damaz91 requested a review from mmohades September 21, 2026 10:42
@damaz91 damaz91 added the area:shopping Issues and pull requests related to the Shopping vertical label Sep 24, 2026
@alexpark20 alexpark20 added status:under-review gov:needs-tc-review Requires review and approval from the Technical Council status:needs-triage Signal that the PR is ready for human triage and removed status:stale-review Applied if a PR is waiting on a reviewer for too long status:under-review labels Sep 29, 2026
@gsmith85

gsmith85 commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

Thanks for catching this, @vishkaty. Moving event_id and created_time into Webhook-Id and Webhook-Timestamp in #342 left them outside Content-Digest, so requiring webhook-id and webhook-timestamp as covered components (MUST) and adding ucp-agent to the example is the right fix.

A few adjustments to make this land cleanly across the spec:

  1. Promote webhook-id and webhook-timestamp into the global "sign-if-present" gate (docs/specification/overview/index.md & docs/specification/signatures.md): Rather than making order/index.md a special-case verification rule, let's add webhook-id and webhook-timestamp directly to the closed set of headers that MUST be covered when present in overview/index.md (IRA step 5) and signatures.md (the Signed Components table and verify_rest_request). Since rest.openapi.json already marks Webhook-Id and Webhook-Timestamp as required: true on order_event_webhook, putting them in the global header-presence gate lets one route-agnostic verify_rest_request implementation handle both REST requests and webhooks without endpoint-specific branching.
  2. SHOULD instead of MUST for Webhook-Id deduplication: Because order webhooks carry full current-state snapshots (not deltas) and Webhook-Timestamp (the immutable event occurrence time) is now signed, a platform that applies snapshots using highest-Webhook-Timestamp-wins (or reconciles via GET /orders/{id}) is already replay-safe without maintaining a separate stateful Webhook-Id store. Deduplicating on Webhook-Id is still useful for fast retry short-circuiting and same-second events, so SHOULD fits better than MUST.
  3. Signing step 2 and Verification step 6 (docs/specification/shopping/order/index.md): Saying "covering ucp-agent, content-digest, webhook-id, and webhook-timestamp at minimum" in Signing step 2 (and checking only webhook-id and webhook-timestamp in Verification step 6) reads as if @method, @authority, @path (@query when present), and content-type are optional. With (1) in place, both steps can simply reference the required components in REST Request Signing / REST Request Verification.
  4. Example Signature value & comment path: Could we swap :MEUCIQDTxNq8h7LGHpvVZQp1iHkFp9+3N8Mxk2zH1wK4YuVN8w...: (ASN.1/DER) on line 764 to :6G4i8TS6oUkGrx8KnCFUpsSPwd74...: to match docs(signatures): make example signature values raw r||s as the spec requires #590, and update order.md to shopping/order/index.md in the playground.md comment?
  5. PR title (fix(order)!:): Since requiring webhook-id and webhook-timestamp in Signature-Input rejects existing webhook signatures that only cover the baseline REST components, could we update the PR title prefix from docs(order): to fix(order)!: (and include the breaking-change justification block in the PR description) so it is flagged in release notes?

vishkaty pushed a commit to vishkaty/ucp that referenced this pull request Oct 3, 2026
… 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.
@vishkaty
vishkaty force-pushed the fix/webhook-sign-standard-headers branch from 1968490 to b65f4a1 Compare October 3, 2026 02:05
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.
@vishkaty
vishkaty force-pushed the fix/webhook-sign-standard-headers branch from b65f4a1 to ddbedfa Compare October 3, 2026 16:07
@vishkaty vishkaty changed the title docs(order): sign Webhook-Id, Webhook-Timestamp, and UCP-Agent in the webhook signature fix(order)!: cover webhook-id and webhook-timestamp in the signing gate Oct 3, 2026
@vishkaty

vishkaty commented Oct 3, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the detailed review. All five are done, rebased onto main b0e81ad.

  1. webhook-id and webhook-timestamp are now in the closed set in overview/index.md
    IRA step 5 and in signatures.md, as a row each in the Signed Components table with a
    footnote, plus both pseudocode paths. order/index.md no longer states a verification
    rule of its own; it points at the global sections.

  2. Deduplication on Webhook-Id is SHOULD, with the full current state reasoning in the
    text. I trimmed it to what the order page already states at :554, :676 and :833, and
    noted that Webhook-Timestamp has one second resolution, so deduplication still does real
    work for events sharing a timestamp.

  3. Signing step 2 and Verification step 6 reference REST Request Signing and REST Request
    Verification rather than naming a subset of components.

  4. The example Signature value is the docs(signatures): make example signature values raw r||s as the spec requires #590 form, and the playground.md comment points
    at shopping/order/index.md.

  5. Retitled fix(order)!: with a BREAKING CHANGE block in the description.

Two things worth flagging.

The Signed Components table is re-padded, so it shows more changed lines than the two new
rows. webhook-timestamp in backticks is wider than the old first column, which fails
markdownlint MD060 under the version super-linter pins. Worth knowing that
markdownlint-cli below 0.49 does not carry MD060 at all, so a local run can look clean
while CI fails.

On the pseudocode, I deliberately kept this to the webhook lines. sign_rest_request on
main also branches on an undeclared ucp_agent, passes no ucp-agent value to
build_signature_base, never appends signature-agent, and branches on body where the
parameter is body_bytes. #785 already fixes all four, including the
signature-agent;key="<label>" form that WBA Interop item 3 requires, so I left them alone
rather than duplicate that work less correctly. The two PRs touch adjacent lines of the same
block and do conflict textually, but it is two declarations and two lines, so rebasing
whichever lands second is mechanical. Glad to rebase on #785 if you prefer taking it first.

Two findings of the same class that I left out, both in the description with reasoning:
Request-Id is required: true on 20 operations across shopping, lodging and common and
sits in no covered component gate; and the DER form value replaced in item 4 still appears at
lodging/booking/rest.md:1590 and lodging/booking/mcp.md:1072, the only two left in the
tree, which #590 never reached. Tell me whether you want either here or separately.

Verification is in the description. The four statements of the gate are checked mechanically:
on unmodified main the check reports both webhook headers missing from all four, on this
branch it passes, and excising any one of the four edits alone puts it back to red.

@gsmith85 gsmith85 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:1590 and lodging/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 uses Webhook-Timestamp as 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.

@igrigorik
igrigorik self-requested a review October 9, 2026 16:53
@vishkaty

Copy link
Copy Markdown
Contributor Author

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
DER values remaining were lodging/booking/rest.md:1590 and
lodging/booking/mcp.md:1072, the only two left in the tree. That count was
wrong. It came from grepping MEUCI, which finds the two request-signing
values and misses the two response-signing values in the same two files, whose
base64 begins MFQCI. Decoding the leading bytes instead of matching a prefix
gives four in the lodging pages:

lodging/booking/mcp.md:1072    30 45 02 21
lodging/booking/mcp.md:1100    30 54 02 20
lodging/booking/rest.md:1590   30 45 02 21
lodging/booking/rest.md:1615   30 54 02 20

The two beginning 30 54 announce an 86 byte SEQUENCE, which matches neither
P-256 DER nor P-384, so those two were never a signature of any supported
curve.

Second correction, to the history rather than the count: #590 did not miss the
lodging tree. No file under lodging/booking existed at the merge commit of
#590. The capability arrived with #780 on 2026-09-24, two months later, and
brought the DER strings that #590 had already replaced in the shopping pages.
The pitfall is a page copied from a pre-fix snapshot of a sibling, which is
also why nothing caught it: no CI or pre-commit step inspects a signature
value, since scripts/validate_examples.py discards the HTTP envelope and
these are unannotated fences.

#934 now carries all four, using the same truncated placeholder #590
established. It also closes a second defect in the same block rather than
leave it half fixed: the Signature-Input at rest.md:1589 omitted
ucp-agent while the request carries a UCP-Agent header, which
signatures.md L434 and L442 make a required covered component. Of the nine
signed example blocks carrying that header, three omitted the component; #934
closes the lodging one, #795 the checkout one, and this PR the order one, so
that class reaches zero when the three land. Trial merges of #934 with this
PR, with #795 and with #782 are all clean, and the four together leave no DER
value and no coverage gap.

The fifth DER value is shopping/order/index.md:752, which this PR already
replaces with its Signature-Input line, so #934 leaves it to you here rather
than duplicating the hunk.

Two further things turned up while checking, both outside either PR and both
yours to want or not:

The published v2026-08-25 tag still carries that same DER value at
shopping/order/index.md:752, in the order event webhook example. Webhooks
are the one class signatures.md L867 says MUST be signed, so it is the
example a webhook implementer copies. release/2026-08-25 takes backports in
the form used by #838, #878 and #886 if you would like one.

signatures.md:495 cites RFC 9421 section 3.3.1 for the ECDSA raw r||s
rule. Section 3.3.1 is RSASSA-PSS Using SHA-512; ECDSA P-256 is 3.3.4 and
P-384 is 3.3.5. The release carries the same citation.

Happy to open either, or neither.

@damaz91 damaz91 removed the status:needs-triage Signal that the PR is ready for human triage label Oct 12, 2026

@igrigorik igrigorik left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few nits and suggestions, otherwise I think this is good to land -- ty for the fix!

Comment thread docs/specification/signatures.md Resolved
Comment thread docs/specification/signatures.md Resolved
Comment thread docs/specification/signatures.md Resolved
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.
@vishkaty

Copy link
Copy Markdown
Contributor Author

Thanks for the review. All four suggestions applied as written in 96d81f1,
with main merged in. The diff is those four suggestions and nothing else;
they land as three hunks because two of them are adjacent.

I swept the same vocabulary across docs/specification. The remaining uses are
correct in context: order/index.md:754 means state kept per delivery, and the
two WBA created/expires mentions in signatures.md use freshness in the
RFC 9421 sense.

One judgment call I left to you. The Description cell for that row still reads
"Idempotency header (state-changing)", so the method framing survives one
column left of the footnote you corrected. Six of the ten parentheticals in
that column state a condition and three describe the component, so it reads
either way. Happy to change it to "(when carried)" in this PR or leave it.

Correcting something I wrote earlier in this thread. I said markdownlint-cli
below 0.49 does not carry MD060. That is wrong. MD060 arrives with the
markdownlint library 0.39.0, and markdownlint-cli 0.46.0 is the first release
to bundle it, so 0.46 through 0.48 do catch it; only 0.45 and below read clean.
Checked by planting a short webhook-id row and running each version against
the repo config. 0.49.0 is clean on the re-padded table here.

@damaz91
damaz91 requested review from sruthi-vandhana and removed request for mmohades October 14, 2026 14:50

@igrigorik igrigorik left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 and ty for iterating on this!

PTAL, one more suggestion before we land.

igrigorik and others added 2 commits October 14, 2026 11:06
…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.
@vishkaty

Copy link
Copy Markdown
Contributor Author

All three applied as written in bee1cf5, on top of your merge of main; thanks for
that. The diff is those three suggestions and nothing else, and the branch is current
with main.

Agreed on the producer half: the dedup and ordering SHOULD rested on retries carrying
the same values, with nothing obliging that. shopping/order is the only capability
with a webhook retry rule today, so there is no sibling to carry the same MUST.

One note for the queue: #938 touches the same lines in signatures.md and
shopping/order/index.md, so it will need a rebase there once this lands.

markdownlint 0.49.0 is clean, and the new Webhook-Id row keeps the table width so
MD060 stays quiet. Nothing else outstanding from my side.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:shopping Issues and pull requests related to the Shopping vertical bug Something isn't working documentation Improvements or additions to documentation gov:needs-tc-review Requires review and approval from the Technical Council

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants