ucp-orders-webhooks

UCP Orders & Webhooks

Before writing code

Fetch live spec: Web-search site:ucp.dev specification order and fetch the page for the exact order data model, webhook envelope, and signature format.

Also fetch https://ucp.dev/specification/reference/ for adjustment types, fulfillment event types, and line item status derivation rules.

Conceptual Architecture

Order Capability (dev.ucp.shopping.order)

Orders represent the post-purchase lifecycle. An order is created when a checkout completes successfully. The order contains:

• Line items with quantity tracking (total, fulfilled)
• Fulfillment expectations (estimated delivery) and fulfillment events (shipped, delivered, etc.)
• Adjustments (refunds, returns, credits, disputes, cancellations)
• Totals (subtotal, tax, discount, fulfillment, fee, total)

Line Item Status Derivation

Status is derived from quantities, not stored:

• fulfilled == total → "fulfilled"
• fulfilled > 0 → "partial"
• fulfilled == 0 → "processing"

Fulfillment Event Types (open string enum)

Common values: processing, shipped, in_transit, delivered, failed_attempt, canceled, undeliverable, returned_to_sender. The set is extensible — new values may appear.

Adjustment Types (open string enum)

Common values: refund, return, credit, price_adjustment, dispute, cancellation. Also extensible.

Webhook Delivery

• Business POSTs the full order entity (not incremental deltas) to the Platform's webhook URL.
• Each delivery includes an event_id (unique) and created_time (RFC 3339).
• Platform MUST respond with 2xx immediately and process asynchronously.
• Business should implement retry with exponential backoff on non-2xx responses.

Webhook Signature (Detached JWT)

This is critical for security:

1. Signing (Business side):
2. Select an EC P-256 key from signing_keys in the Business's /.well-known/ucp profile
3. Create a Detached JWT (RFC 7797) over the request body
4. Set kid in the JWT header to match the key ID
5. Include the signature in the Request-Signature HTTP header

1. Verification (Platform side):
2. Extract Request-Signature header
3. Parse JWT header for kid
4. Fetch Business's /.well-known/ucp profile, find the matching key
5. Verify the JWT signature against the request body
6. Reject if verification fails

Implementation Guidance

Business:

• Generate EC P-256 key pair; publish public key in discovery profile
• After checkout completion, create order entity
• On every fulfillment event or adjustment, POST the full updated order to the platform webhook URL with a fresh signature
• Implement retry logic (exponential backoff, max attempts)

Platform:

• Expose a webhook endpoint URL (declared in order capability config)
• Verify Request-Signature on every incoming webhook
• Process order updates asynchronously (respond 2xx first)
• Handle idempotency using event_id

Fetch the conformance test suite at https://github.com/Universal-Commerce-Protocol/conformance for webhook test cases.