Skip to main content

Debugging signatures

Signature mismatches are the #1 integration stall — and impossible to debug blind, because a correct server never reveals what it expected. The sandbox fixes that with a dedicated endpoint that accepts an invalid signature on purpose and echoes back the server-side computation.

POST /debug/echo-signature (sandbox only)​

Send any request with your valid test apiKeyId and any signature attempt:

Response
{
  "success": true,
  "canonicalString": "POST\n/api/v1/partner/debug/echo-signature\n1753260000000\n{\"probe\":true}",
  "canonicalParts": {
    "method": "POST",
    "path": "/api/v1/partner/debug/echo-signature",
    "timestamp": "1753260000000",
    "bodyBytes": 14,
    "bodySha256": "9c9d…"
  },
  "expectedSignature": "3f2a…",
  "receivedSignature": "deadbeef…",
  "signatureMatches": false,
  "timestampWithinSkew": true,
  "note": "Sign hex(HMAC-SHA256(canonicalString, hmacSecret)) over the EXACT raw body bytes — do not re-serialize JSON after signing."
}

How to use it​

  1. Point your failing client at /api/v1/partner/debug/echo-signature.
  2. Compare canonicalParts with what your code signed:
    • path differs → you included the query string, or a proxy rewrote the path.
    • timestamp differs → you signed a different value than you sent.
    • bodySha256 differs → your transmitted bytes ≠ signed bytes (re-serialisation, encoding, or a middleware mutating the body).
  3. When expectedSignature matches what your code produces, point back at the real endpoints — done.

Live keys get 403 SANDBOX_ONLY — this endpoint never exists in production.