Guides
My Account

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)

POST https://example.com/webhooks/walmart/reports
Content-Type: application/json
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)

POST https://example.com/webhooks/walmart/reports
Content-Type: application/json
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

{ "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)

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

  • See request and download a report for the core flow.
  • Review limits, retention, and file formats for retention and file size guidance.

Updated 3 days ago