7. Order webhooks & identity linking

Two UCP capabilities involve external integrations beyond simple request/response. This page explains what they do, how to configure them, and how to verify they work.

7.1 Order webhooks (dev.ucp.shopping.order)

When the Order and webhooks capability is enabled, your shop POSTs a signed event to the platform's webhook_url every time an order's state changes — placed, shipped, delivered, canceled, returned, etc.

How it works

sequenceDiagram
    participant Customer
    participant Shop as Shopware<br/>(your shop)
    participant Platform as Platform agent<br/>(ChatGPT / Gemini / …)

    Customer->>Shop: Order placed via UCP /complete
    Shop-->>Platform: 200 OK { order_id }
    Note over Shop: Order state-machine transitions
    Shop->>Platform: POST {webhook_url}<br/>+ RFC 9421 Signature
    Platform->>Platform: Verify signature against<br/>signing_keys from /.well-known/ucp
    Platform-->>Shop: 200 OK

Each webhook is signed per RFC 9421 (HTTP Message Signatures) and carries an RFC 9530 Content-Digest header so the platform can authenticate the message end-to-end. Shopware also includes Webhook-Id and Webhook-Timestamp headers so platforms can detect duplicates and reject stale deliveries.

Verifying with the simulator

1. Start the simulator (npm run dev in the simulator/ folder).
2. Pick the Webhooks: open listener scenario and click Run.
3. The simulator displays the webhook URL you should configure on your shop side.
4. The platform usually advertises this URL in its UCP profile under dev.ucp.shopping.order.config.webhook_url; Shopware reads it during negotiation and validates the target URL before dispatching.
5. Place a test order in your shop.
6. The webhook appears in the simulator's left-sidebar log within seconds, marked verified if the signature checked out.

If the badge says failed, the simulator shows the verification failure reason (typically: key not found, signature mismatch, or digest mismatch) so you can investigate.

7.2 Identity Linking (dev.ucp.common.identity_linking)

When this capability is enabled, your shop runs a per-Sales-Channel OAuth 2.0 Authorization Server. AI agents use the standard OAuth Authorization Code flow with PKCE to obtain a user identity token, then present it on subsequent UCP requests so they can act on behalf of a real customer account — unlocking saved addresses, member pricing, wishlists, and order history.

How it works

sequenceDiagram
    participant Agent as Platform agent
    participant Buyer
    participant Shop as Shopware OAuth AS<br/>(per Sales Channel)

    Agent->>Shop: GET /.well-known/oauth-authorization-server
    Shop-->>Agent: { authorization_endpoint, token_endpoint, scopes_supported, … }
    Agent->>Buyer: Open authorization URL<br/>(code_challenge S256, state, scope=…)
    Buyer->>Shop: Sign in & consent
    Shop-->>Agent: code, state, iss (redirect)
    Agent->>Shop: POST /token (code + code_verifier)
    Shop-->>Agent: access_token (Bearer)
    Agent->>Shop: GET /ucp/v1/...  Authorization: Bearer ...
    Shop-->>Agent: User-authenticated UCP response

Which operations use OAuth?

OAuth is optional for anonymous shopping. A buyer can browse, build a cart, and complete a guest checkout without linking an account. OAuth is used when the platform needs user-bound access, for example order history or future account-specific operations.

Today the gated operations are:

• dev.ucp.shopping.order:read — read past orders
• dev.ucp.shopping.order:manage — cancel / return / modify an order

Invalid bearer tokens are fail-closed: Shopware rejects the request instead of treating it as anonymous.

If your business model requires authentication for every transaction (B2B-only, age-restricted goods, etc.), your developer can add dev.ucp.shopping.checkout:manage to the gated scopes via the configuration object exposed in the profile.

Verifying with the simulator

1. In the simulator, pick Identity: OAuth metadata discovery. It confirms your /.well-known/oauth-authorization-server document exposes PKCE (S256) and the iss parameter — both mandatory.
2. Then pick Identity: build authorization URL (PKCE). The simulator renders the actual authorization URL ready to open in your browser. Sign in with a test customer, accept the consent screen, and you're returned to the simulator with an access token bound to the run.
3. From there on, every UCP call the simulator makes will include the Authorization: Bearer … header — useful for verifying that your shop's user-authenticated branches work.

→ Next: Troubleshooting & FAQ