Guides
My Account

Security and authenticity

Follow these steps to validate that performance webhook deliveries come from Walmart and are intended for your sellers. You will verify request integrity, protect against replay, check seller authorization, and acknowledge only after a durable write.

Before you begin

  • Use HTTPS for your callback URL
  • Store a webhook secret in a secure vault
  • Sync server clocks with NTP to reduce clock skew

Steps

Step 1. Require HTTPS

Reject plain HTTP. Accept only TLS 1.2 or higher. Disable weak ciphers.

Step 2. Read required headers

Expect these headers on every delivery. Header names may vary by framework; treat them case-insensitively:

  • WM_SEC.TIMESTAMP: Unix epoch seconds when the event was created
  • WM_SEC.SIGNATURE: Base64 encoded HMAC SHA256 signature
  • WM_SEC.KEY_ID (optional): identifier for the active secret during rotation

Step 3. Validate the signature

Compute a signature and compare it to WM_SEC.SIGNATURE with a constant time compare.

Canonical components

  • HTTP method in uppercase
  • Request path with query string, exactly as received
  • WM_SEC.TIMESTAMP value
  • SHA256 digest of the raw request body in lowercase hex

String to sign

<METHOD>\n<PATH_AND_QUERY>\n<WM_SEC.TIMESTAMP>\n<SHA256_HEX_OF_BODY>

Computation

signature = base64( HMAC_SHA256( secret, string_to_sign ) )

JavaScript example

import crypto from "crypto"; function sha256Hex(buf) { return crypto.createHash("sha256").update(buf).digest("hex");
} export function verifySignature({ method, pathAndQuery, bodyBuffer, headers, secret }) { const ts = headers["WM_SEC.TIMESTAMP"] || headers["wm_sec.timestamp"]; const sig = headers["WM_SEC.SIGNATURE"] || headers["wm_sec.signature"]; if (!ts || !sig) return false; const toSign = [method.toUpperCase(), pathAndQuery, String(ts), sha256Hex(bodyBuffer)].join("\n"); const expected = crypto.createHmac("sha256", secret).update(toSign, "utf8").digest("base64"); const a = Buffer.from(sig); const b = Buffer.from(expected); return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Step 4. Enforce a replay window

Use the signature scheme described below. Verify timestamp and signature, enforce replay protection, confirm seller authorization, store, deduplicate, then return 2xx.

If your endpoint is failing, the platform can send a webhook failure notification email to administrator email addresses on your account. Refer to Troubleshooting and delivery health.

Step 5. Confirm seller authorization

Verify that the seller identifier in the payload maps to a seller you manage. For approved solution providers, check the mapping between the partner account and the target seller.

Step 6. Persist and deduplicate

Store the payload and deduplicate using the delivery identifier exposed to integrators (for example, a top-level eventId field or a documented delivery header). Make handlers safe to run more than once.

Step 7. Acknowledge correctly

Return 200 (OK) or 202 (Accepted) only after a durable write and after you enqueue work. Use non-2xx to signal a retry.

Typical responses

  • 200 OK and stored
  • 202 Accepted for asynchronous processing
  • 4xx Permanent failure such as bad signature or unauthorized seller
  • 5xx Temporary failure. Walmart retries non-2xx responses

Step 8. Log and monitor

Log headers, the computed signature, and the validation result. Alert on spikes in signature failures or retries. Track broken endpoints.

Step 9. Rotate secrets

Support two active secrets during rotation and include WM_SEC.KEY_ID in validation to pick the correct secret. Rotate at least every ninety days or on owner change.

Step 10. Test end to end

If available for your account, use the test delivery endpoint to send a sample event to your callback URL. Log the raw request including headers and confirm signature verification and replay checks pass.
How-to: Test in sandbox
API reference: Test notification

Reference

Signature scheme v1

  • Algorithm: HMAC SHA256 with Base64 output
  • String to sign: method, path with query, timestamp, body hash
  • Replay window: five minutes with two minutes of allowed skew
  • Idempotency retention: reject duplicate deliveries for seven days using the documented delivery identifier

Next steps

Reference guide

  • This guide explains how to verify signatures, protect against replay, and acknowledge only after a durable write.
  • Test notification: Triggers a sample delivery to your callback URL to validate your integration.

Related


Updated 28 days ago