Skip to content

test: add order-event webhook structural conformance module - #73

Merged
carolinerg1 merged 2 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:webhook-coverage
Aug 5, 2026
Merged

test: add order-event webhook structural conformance module#73
carolinerg1 merged 2 commits into
Universal-Commerce-Protocol:mainfrom
vishkaty:webhook-coverage

Conversation

@vishkaty

@vishkaty vishkaty commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

What

Adds webhook_structure_test.py: structural conformance for the order event webhook contract that the 2026-04-08 order specification pins beyond "an event arrives" (which webhook_test.py already covers):

  • Required headers per Standard Webhooks: Webhook-Id and a unix Webhook-Timestamp (order.md, Order Event Webhook, Required Headers).
  • The body is the FULL order entity, never a delta: the schema required properties of order.json are used as the floor for "fully populated", and ids must reconcile with the originating checkout (order.md, Events and its Business guidelines).
  • The signing envelope when deliveries are signed: the four required headers, a sha-256 Content-Digest computed over the raw body bytes (signatures.md requires sha-256 over raw bytes; MockWebhookServer now records raw bytes so re serialized JSON cannot mask a digest mismatch), and the signed component list. This checks structure, not cryptographic verification of the signature value against published keys; that would be a natural follow up.

Design decisions stated plainly for review

  • A merchant that sends UNSIGNED deliveries produces a loud per test skip, not a failure, even though order.md says payloads MUST be signed. The reference server does not sign deliveries today, so a hard failure would redden main. The skip message names the violated MUST so it reads as a finding rather than a pass. If you prefer a failure here we are happy to flip it.
  • The ucp-agent signed component is graded conditionally: the signatures.md component table requires it whenever the header is present, but the order.md example webhook signature omits it. That inconsistency has a proposed fix in flight (ucp#659); until the spec is self consistent a merchant following the example verbatim is not failed, and the skip cites the discrepancy.
  • A 403 from the simulation endpoint skips as "simulation secret rejected", distinct from 404/405 "no simulation path", so a tester misconfiguration cannot masquerade as a missing capability.

Verification

Full suite against the reference server per the CI recipe: all 17 test files pass (this module: 3 pass, 2 loud skips on the unsigned reference; existing webhook_test.py unaffected, 3/3). Every assertion was mutation tested against a modified merchant: delta body, wrong ids, dropped Webhook-Id, millisecond timestamp, sha-512 digest, digest over re serialized JSON, and a component list omitting ucp-agent each turn the specific test red, and a correctly signed delivery turns the signature tests green. Pinned pre-commit clean.

Covers the 2026-04-08 order.md delivery contract beyond event arrival
(webhook_test.py): Standard Webhooks headers (Webhook-Id, unix
Webhook-Timestamp), the fully populated order entity as body on the
'Order created' and update events (order.json required properties, ids
reconciling with the originating checkout, never a delta), and the
webhook signing contract (UCP-Agent + Signature + Signature-Input +
Content-Digest, SHA-256 Content-Digest over the raw body, and ucp-agent
among the signed components per the signatures.md component table).

The signature tests skip with an explicit message while the server
sends unsigned deliveries, mirroring how other structural tests skip on
shapes the server does not emit; the update-event test skips when the
server exposes no /testing/simulate-shipping path. MockWebhookServer
now records the raw request bytes so Content-Digest can be verified
without re-serializing JSON.
@damaz91 damaz91 added status:needs-triage Signal that the PR is ready for human triage status:under-review and removed status:needs-triage Signal that the PR is ready for human triage labels Aug 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants