# 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:

```javascript
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:

```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)

```

> Also enforce (see the examples): HTTPS/TLS 1.2+ only, a replay window against `WM_SEC.TIMESTAMP` (the examples use a symmetric ±5 min window, which covers stale replays and modest clock skew), confirm the seller identity in the payload is one you're authorized for, dedupe by delivery/event id (~7 days), and return `2xx` only after a durable write. Respond within 3 seconds — repeated failures trigger a webhook failure notification email to account administrators.

> For complete handlers with route wiring, event dispatch, and tests, see:
> 
> * [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/walmart-webhooks/examples/express/)
> * [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/walmart-webhooks/examples/nextjs/)
> * [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/walmart-webhooks/examples/fastapi/)

## Common Event Types

Each delivery carries an `eventType` (with a `resourceName` and `eventVersion`). Subscribe via Walmart's Webhooks Subscription API.

> Confirm these names for your account. Only `PO_CREATED`, `INVENTORY_OOS`, `BUY_BOX_CHANGED`, and `RETURN_CREATED` (marked ✅ below) were verified verbatim against Walmart's [Get event types](https://developer.walmart.com/us-marketplace/docs/get-event-types) API. The remaining rows — and their `resourceName` mappings — are illustrative; event availability varies by program, so call Get event types for your own account before subscribing to them.

| eventType | resourceName | Triggered When |
| --- | --- | --- |
| ✅ `PO_CREATED` | `ORDER` | A new purchase order is routed to you for fulfillment |
| `PO_LINE_AUTOCANCELLED` | `ORDER` | A PO line is auto-cancelled |
| `INTENT_TO_CANCEL` | `ORDER` | A customer requests to cancel an order |
| ✅ `INVENTORY_OOS` | `INVENTORY` | An item goes out of stock |
| `OFFER_PUBLISHED` | `ITEM` | An offer becomes published/live |
| `OFFER_UNPUBLISHED` | `ITEM` | An offer is unpublished |
| ✅ `BUY_BOX_CHANGED` | `PRICE` | Buy Box ownership/price changes for an item |
| ✅ `RETURN_CREATED` | `ReturnsAndRefunds` | A customer creates a return |
| `REPORT_STATUS` | `REPORTS` | A requested report is ready |
| `SELLER_PERFORMANCE_ALARMS` | `ITEMS` | A seller performance alarm fires |

> For the full list, call the [Get event types](https://developer.walmart.com/us-marketplace/docs/get-event-types) API. See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/walmart-webhooks/references/overview.md).

## Environment Variables

```bash
WALMART_WEBHOOK_SECRET=your_webhook_secret   # Shared secret from the Webhooks Subscription setup

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 walmart --path /webhooks/walmart

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/walmart-webhooks/references/overview.md) - Walmart webhook concepts and event types
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/walmart-webhooks/references/setup.md) - Configure the performance webhook endpoint and secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/walmart-webhooks/references/verification.md) - Signature verification details and gotchas