Troubleshooting and delivery health

Use this guide to diagnose delivery issues, confirm retries, and keep your webhook endpoints healthy. It covers quick checks, signature failures, idempotency, and recommended instrumentation.

Check the following

Confirm subscription
Use Get all subscriptions to confirm subscription (resource FEEDS, event SELLER_PERFORMANCE_NOTIFICATIONS, unified endpoint URL).
Reproduce in sandbox
Send a sample using Test notification. See Test in sandbox.
Inspect logs
Capture request headers and raw body bytes. Verify you are logging WM_SEC.TIMESTAMP, WM_SEC.SIGNATURE, and a delivery identifier (for example, eventId).
Return a 2xx only after a durable write
Acknowledge quickly after you store the event and enqueue any long work asynchronously.

Common symptoms and fixes

Symptom	Likely cause	What to check	How to fix
No deliveries arriving	Wrong endpoint URL or disabled subscription	`endpointUrl` in your subscription, firewall, TLS setup	Update the subscription URL, allow traffic from Walmart, confirm TLS
401 or 403 from your service	Signature or seller validation failed	Header names and casing, timestamp skew, secret lookup, seller mapping	Align header parsing, adjust allowed skew window, rotate or correct the secret, fix seller mapping
400 from your service	Schema validation is too strict	Envelope fields, unknown fields in payload	Accept the shared envelope and ignore unknown fields defensively
408 or 5xx from your service	Slow synchronous processing	Downstream calls during request, large payload processing	Acknowledge fast, move work to a queue, increase timeouts thoughtfully
Duplicate processing	Missing idempotency	Use of a delivery identifier on writes	Add a uniqueness constraint or conflict-safe upsert
Retries never stop	Endpoint always non-2xx	Healthcheck route, error logs, circuit breakers	Fix the root cause, then confirm 2xx with a sandbox test
Only one event type arrives	Per event routing precedence	Internal precedence when both unified and per event endpoints exist	Prefer the most specific route and document your rule

Signature verification failures

Verify headers exactly as sent. Required headers include WM_SEC.TIMESTAMP and WM_SEC.SIGNATURE (and optionally WM_SEC.KEY_ID if you rotate secrets).
Validate the signature before processing the body.
Use the exact request path and raw body bytes when computing the HMAC.
Reject any request that fails verification and log the reason.
Refer to Security and authenticity.

Retries and backoff

Walmart retries when your endpoint does not return 2xx.
Each retry is signed. Always verify signatures on retries.
Ensure your receiver is idempotent and safe to retry.
When healthy, you should see a single successful delivery with no subsequent retries.
Refer to Test in sandbox to validate retry behavior.

Idempotency and deduplication

Use a delivery identifier (for example, a top-level eventId or a documented delivery header) as the idempotency key.
Make writes conflict-safe by using an upsert or a uniqueness constraint on the event identifier.
Log both accepted and deduplicated events to prove correctness during audits.

Health monitoring and alerting

Track these key indicators:

2xx rate per endpoint and event type
Retry rate and time to recovery
Median and p95 acknowledgment latency
Signature verification failure rate

Recommended alerts:

2xx rate below threshold for 5 minutes
Retries above threshold for 10 minutes
Signature failures above threshold for 5 minutes

Broken endpoints

If Walmart detects repeated failures, the platform can mark your endpoint as broken and notify your contacts. When that happens:

Fix the root cause in your service.
Validate with Test in sandbox.
Resume normal traffic and watch error rates.

Sandbox tips

Start with small payloads, then test larger alarm sets or metric arrays.
Intentionally return a non-2xx once to observe retry cadence.
Validate that your logs include headers and the raw body used for verification.

Next steps

Verify your signature code and seller checks in Security and authenticity.
Reproduce issues with Test in sandbox.
Review payload shapes in the Event catalog.

Reference guide

This guide explains how to monitor delivery success, handle retries, and remediate failing endpoints.

Get all subscriptions: Returns all subscriptions on your account for auditing and troubleshooting.
Update subscription: Changes an existing subscription (endpoint URL, event set, or status).
Delete subscription: Removes a subscription you no longer need.
Test notification: Triggers a sample delivery to your callback URL to validate your integration.