Signed operations
A return carries its refund amount, method and status, so
listReturns and getReturn are the signed reads for refunds.
A response is signed when the call is made with a secret key and the store has a signing secret. A call made with a publishable key is never signed, because a publishable key holds no secret to verify with. A call made with a marketplace key to the returns operations is not signed. Every other operation returns no signature headers.
Signature headers
{timestamp} is the value of X-Signature-Timestamp and {body} is the exact bytes of the response after transport decompression. The body is neither parsed nor re-serialised: a different key order or different whitespace is a different string and produces a different signature.
Signing secret
The secret that signs a response is the one the caller uses to sign requests:- A key issued to an application connected through Login with GC signs with that connection’s own
signing_secret. - Any other key signs with the store’s signing secret, shown under Integrations → API keys.
Verifying with the SDK
verifyResponseSignature recomputes the signature with Web Crypto and compares it in constant time. It runs on Node.js 18 and later and on other server runtimes that provide Web Crypto.
The function returns
true when the signature matches under any supplied secret and the timestamp is within tolerance. It returns false for a missing or malformed header, a stale timestamp, a changed body and a wrong secret. A response that carries no signature headers returns false.
The generated service methods return parsed objects, so a response is verified on a direct fetch call as above.
Verifying without the SDK
The recipe has four steps:- Read
X-Signature-TimestampandX-Signaturefrom the response. - Take the decoded response body as received.
- Compute
HMAC-SHA256(signing_secret, "{timestamp}.{body}")and encode the digest as base64. - Compare it with
X-Signaturein constant time, and reject a response whose timestamp is more than five minutes from the current time.

