Subscribe to an event notification

You can use webhook notifications to subscribe to specific events and receive real-time updates when those events occur.

How to create a subscription

To set up a webhook subscription:

1. Specify the event type you want to monitor.
2. Provide your app’s destination URL (must be a public HTTP or HTTPS endpoint).
3. Configure notification preferences as needed.

You can subscribe to multiple events in a single request.

Authentication options

Walmart supports several authentication methods. OAuth is the recommended method. For details, visit the /us-marketplace/docs/delegated-access-authorization guide.

If you include custom headers in the headers field, the authURL must return an HTTPS status code 200. The response must include:

• access_token
• expires_in

When sending a notification to endpointUrl, Walmart includes the access_token in the request headers using the key authHeaderName and the value Bearer \<access_token>. Any custom headers from the headers field are also included.

Resource authorization

To subscribe to a resource’s events, you must have the appropriate delegated access scope:

• view_only or full_access: You can subscribe to all events for that resource.
• no_access: You cannot subscribe to any events for that resource.

You can still retrieve event types and subscription details for all resources, regardless of your access scope.

Step 1: Test your destination URL

Before creating a subscription, validate your destination URL using the /us-marketplace/reference/testnotification API. Ensure the URL is publicly accessible via HTTP or HTTPS.

Provide the following parameters:

• eventType: Name of the event (e.g., OFFER_UNPUBLISHED). For a full list, use the Event Types API.
• eventVersion: Depends on the event type. Refer to the Notifications overview article for details. For example, Offer unpublished event uses V1.
• resourceName: Functional category for the event (e.g., Item).
• eventURL: Destination URL for receiving notifications.

For a sample request, refer to the Test Notification API Reference.

Step 2: Create a subscription

After confirming your destination URL works, create a subscription using the Create subscription API.

Steps:

1. Call the API and provide all required parameters.
2. Use the Event Types API to retrieve available events and resource names.
3. Specify values for the authDetails parameters.

Upon success, Walmart returns a subscription ID.

Step 3: Set up notification acknowledgment

Your system must respond to Walmart’s notifications with an HTTP 2xx status code.
If no acknowledgment is received:

• First retry: 5 minutes later
• Second retry: 15 minutes after the first
• Third retry: 45 minutes after the second

(Optional) Step 4: Retrieve active subscriptions

To verify your active subscriptions, call the All subscriptions API. It returns a list of your current subscriptions.

Receiving notifications

Once your subscription is active and tested, Walmart sends notifications to your destination URL whenever the subscribed event occurs.