---
updatedAt: 2026-07-09T21:27:20.000Z
---

# Report status notifications

Use notifications to avoid polling for report readiness. When a report finishes (or fails), the service sends an HTTPS POST to your callback URL with a JSON payload that includes the request ID and a download link when available.

## When to use notifications

* You submit many report requests and want to avoid periodic status checks.
* You need near‑real‑time processing when a report is ready.
* Your downstream system triggers jobs based on specific report types or schedules.

## Event types

The service emits these events for on‑request reports:

* `report.completed` – the report file is ready to download.
* `report.failed` – the request could not be completed.

## Delivery format

Notifications are sent as an HTTPS POST with a JSON body. Your endpoint must return **2xx** within 10 seconds. If your endpoint returns non‑2xx or times out, the service retries delivery using exponential backoff.

### Example request (report.completed)

```http
POST https://example.com/webhooks/walmart/reports
Accept: application/json
Content-Type: application/json
WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6
WM_SEC.ACCESS_TOKEN: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
header 'WM_SVC.NAME: Walmart Service Name
User-Agent: Walmart-Reports-Webhook/1.0
X-Event-Type: report.completed
X-Event-Id: 6c6a9b8f-7a2e-4b9a-9f4b-3f1b9c1ce111

{
  "event": "report.completed",
  "requestId": "rpt-78910",
  "reportType": "ITEM_PERFORMANCE",
  "status": "COMPLETED",
  "format": "CSV",
  "downloadUrl": "https://marketplace.walmartapis.com/download/rpt-78910/file.csv",
  "expiresAt": "2025-09-30T10:15:00Z",
  "filters": {
    "sku": ["SKU123", "SKU456"],
    "startDate": "2025-08-01",
    "endDate": "2025-08-31"
  },
  "createdAt": "2025-09-01T10:15:00Z",
  "completedAt": "2025-09-01T10:18:23Z",
  "correlationId": "a8a7a6f5-3de1-4f02-8a2c-1b23cdef9abc"
}
```

### Example request (report.failed)

```http
POST https://example.com/webhooks/walmart/reports
Content-Type: application/json
Accept: application/json
Content-Type: application/json
WM_QOS.CORRELATION_ID: b3261d2d-028a-4ef7-8602-633c23200af6
WM_SEC.ACCESS_TOKEN: eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM.....
header 'WM_SVC.NAME: Walmart Marketplace
User-Agent: Walmart-Reports-Webhook/1.0
X-Event-Type: report.failed
X-Event-Id: 9f7dd7a3-1f65-4a27-8d76-2a2c07f4d222

{
  "event": "report.failed",
  "requestId": "rpt-78910",
  "reportType": "ITEM_PERFORMANCE",
  "status": "FAILED",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "startDate must be before endDate"
  },
  "createdAt": "2025-09-01T10:15:00Z",
  "failedAt": "2025-09-01T10:15:02Z",
  "correlationId": "a8a7a6f5-3de1-4f02-8a2c-1b23cdef9abc"
}
```

## Payload schema

```json
{
  "event": "report.completed | report.failed",
  "requestId": "string",
  "reportType": "string",
  "status": "COMPLETED | FAILED",
  "format": "CSV | XLSX | ZIP",
  "downloadUrl": "string (present only when status is COMPLETED)",
  "expiresAt": "ISO 8601 datetime (optional)",
  "filters": "object (same structure used when requesting the report)",
  "createdAt": "ISO 8601 datetime",
  "completedAt": "ISO 8601 datetime (present on COMPLETED)",
  "failedAt": "ISO 8601 datetime (present on FAILED)",
  "correlationId": "string"
}
```

## Security

* **TLS:** Only HTTPS endpoints are supported.
* **Authentication:** If your endpoint requires a token or basic auth, configure it on your side and validate the header in your handler.
* **Allowlist:** If your perimeter requires IP allowlisting, add the ranges provided by your network team.
* **Replay protection:** Use `X-Event-Id` to de‑duplicate replays and store processed IDs for at least 24 hours.

## Retry policy

* The service retries failed deliveries using **exponential backoff**.
* Your endpoint should be **idempotent**. Processing the same event more than once must not create duplicate work.
* Return a 2xx only **after** you persist the event.

## Correlation and tracing

* `correlationId` mirrors `WM_QOS.CORRELATION_ID` used in your original request.
* Log the pair `(requestId, correlationId)` so you can trace a report from creation through completion.

## Sample receiver (Node.js/Express)

```js
import express from "express";
import crypto from "crypto";

const app = express();
app.use(express.json({ type: "application/json" }));

app.post("/webhooks/walmart/reports", async (req, res) => {
  const eventType = req.get("X-Event-Type");
  const eventId = req.get("X-Event-Id");
  const payload = req.body;

  // Idempotency: ignore if already processed
  const alreadyHandled = await hasEventId(eventId);
  if (alreadyHandled) return res.sendStatus(200);

  if (eventType === "report.completed") {
    await queueDownloadJob(payload.requestId, payload.downloadUrl);
  } else if (eventType === "report.failed") {
    await createAlert(payload.requestId, payload.error);
  }

  await storeEventId(eventId);
  res.sendStatus(200);
});

app.listen(3000, () => console.log("Webhook listening on 3000"));
```

## Troubleshooting

* **No events received:** confirm your endpoint is publicly reachable over HTTPS and returns 2xx within 10s.
* **Duplicate deliveries:** implement idempotency by storing and checking `X-Event-Id`.
* **Download link expired:** re‑request the report or submit a new request if the retention window has passed.

## Next steps

* Refer to **request and download a report** for the core flow.
* Review **limits, retention, and file formats** for retention and file size guidance.