walmart-webhooks

Walmart Webhooks

When to Use This Skill

• How do I receive Walmart Marketplace webhooks?
• How do I verify Walmart webhook signatures (WM_SEC.SIGNATURE)?
• How do I handle PO_CREATED, INVENTORY_OOS, or BUY_BOX_CHANGED events?
• Why is my Walmart webhook signature verification failing?
• Setting up a Walmart performance webhook endpoint

Verification (core)

Walmart Marketplace performance webhooks sign each delivery with HMAC-SHA256 keyed on a shared webhook secret. The signature is not over the raw body directly — Walmart builds a canonical string from four components joined by newlines, then HMACs that:

<HTTP_METHOD>\n<REQUEST_PATH_AND_QUERY>\n<WM_SEC.TIMESTAMP>\n<SHA256_HEX_OF_RAW_BODY>

• Method — uppercased (POST).
• Path + query — the request path including the query string, exactly as received.
• Timestamp — the WM_SEC.TIMESTAMP header value (Unix epoch seconds when the event was created).
• Body hash — SHA256 of the raw, unparsed body, as lowercase hex (hash the raw bytes, not a re-serialized JSON).

Then signature = base64(HMAC_SHA256(secret, stringToSign)), compared timing-safe against the WM_SEC.SIGNATURE header. Headers are case-insensitive; WM_SEC.KEY_ID (optional) identifies the active secret during rotation.

Node:

const crypto = require('crypto');

function verifyWalmartWebhook({ method, pathWithQuery, timestamp, rawBody, signature, secret }) {
  if (!timestamp || !signature) return false;
  const bodyHash = crypto.createHash('sha256').update(rawBody).digest('hex'); // lowercase hex
  const stringToSign = [method.toUpperCase(), pathWithQuery, timestamp, bodyHash].join('\n');
  const expected = crypto.createHmac('sha256', secret).update(stringToSign).digest('base64');
  try {
    return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  } catch {
    return false; // length mismatch = invalid
  }
}

Python:

import hmac, hashlib, base64

def verify_walmart_webhook(method, path_with_query, timestamp, raw_body, signature, secret):
    if not timestamp or not signature:
        return False
    body_hash = hashlib.sha256(raw_body).hexdigest()  # lowercase hex
    string_to_sign = "\n".join([method.upper(), path_with_query, timestamp, body_hash])
    expected = base64.b64encode(
        hmac.new(secret.encode(), string_to_sign.encode(), hashlib.sha256).digest()
    ).decode()
    return hmac.compare_digest(signature, expected)