UCP Message Signatures: verify requests and webhooks

A guide to UCP signatures with RFC 9421, body digests, ES256, JWK discovery, key rotation, verification, and webhook security.

Published 12 September 2026 . Part of the UCP implementation guide.

UCP uses HTTP Message Signatures to prove the origin and integrity of exchanges. The foundation is RFC 9421, combined with a body digest, JWK keys published in the UCP profile, and idempotency keys for replay protection.

Key takeaways

Every verifier must support ES256; ES384 and EdDSA are optional.

Content-Digest protects the body under RFC 9530.

Every UCP webhook must be signed.

What does a UCP signature protect?

The Message Signatures specification covers impersonation, tampering, replay against another request, and method or path confusion. The signature therefore protects more than the JSON body.

Signed components can include method, authority, path, digest, and idempotency key. Changing POST /checkout to another route invalidates the signature even when the body is unchanged.

Which standards and formats apply?

Element	UCP rule
signature format	RFC 9421
body digest	RFC 9530 over raw bytes
algorithm	ES256 verification required, ES384 and EdDSA optional
key format	JWK under RFC 7517
discovery	`keys[]` in `/.well-known/ucp`
replay defense	business-layer idempotency key

Public keys in the UCP manifest are identified by kid. The verifier selects the matching key, rebuilds the signature base, and checks the elliptic-curve signature.

As of version 2026-08-25, the profile publishes these JWKs in the root keys[] array. The signing_keys[] field belongs to the historical 2026-04-08 schema and must not be used by a profile that advertises compatibility with the current version.

How should a REST request be verified?

Parse the components declared by Signature-Input.
Require the components mandated for the operation.
Resolve keyid from the sender’s validated profile.
Recalculate Content-Digest over received bytes before parsing or reformatting JSON.
Rebuild the RFC 9421 signature base in declared order.
Verify the signature with the public key.
Apply idempotency rules after authentication succeeds.

Recalculating the digest after parsing and serializing JSON is incorrect. Whitespace and key order may change. RFC 9530 protects the bytes that actually crossed the network.

Signatures and idempotency solve different problems

The signature answers “who sent what?” The idempotency key answers “did this logical operation already have an effect?” UCP places replay protection at the business layer, not in a signature timestamp.

A state-changing operation includes a key with at least 128 bits of entropy. The server stores it for at least 24 hours, with 48 hours recommended. A duplicate returns the cached response. Reusing the same key with a different body returns HTTP 409.

Which messages should be signed?

Platforms should sign all requests when they select HTTP Message Signatures. Webhooks must be signed because recipients otherwise cannot authenticate a server-initiated push.

Signatures are recommended for payment authorization and Checkout completion responses. They are optional for read-only Catalog calls, low-risk Cart operations, and some error responses. OAuth, mTLS, or API keys can also authenticate operations where supported.

Key rotation and caching

kid permits two or more keys during rotation. A verifier should refresh the profile when a key is unknown without automatically trusting an unvalidated profile. Removing a compromised key from the profile is the mechanism for invalidating old signatures.

An excessively long cache can retain a removed key. No cache makes every request depend on profile availability. A sound policy combines a short lifetime, refresh on key_not_found, and a strictly bounded fallback to the last validated profile.

For the complete deployment sequence, see the merchant UCP implementation guide.

Sources

Back to the UCP implementation guide · All notes · Lire en français