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:

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

Keep the existing signature scheme (HMAC SHA256, Base64). Verify WM_SEC.TIMESTAMP and WM_SEC.SIGNATURE. Enforce a five‑minute replay window and allow two minutes of clock skew. Confirm seller authorization, store, deduplicate, then return 2xx.

If your endpoint is failing, the platform can send a webhook failure notification email to your account contacts. 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

Create or update your subscriptions: Subscribe to performance webhooks
Review schemas and examples in the Event catalog
Monitor production behavior in Troubleshooting and delivery health

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.