--- updatedAt: 2026-06-25T19:32:13.000Z --- # Create subscription Create one or more webhook subscriptions for event notifications by selecting an event type, event version, resource name, and providing a destination event URL. Use the Get Event Types API to retrieve available event types, versions, and resource names. Configure the eventUrl to receive notifications. URL authentication options - If authMethod is BASIC_AUTH, Walmart passes an authentication header to the eventUrl using authHeaderName as the header key and the Base64-encoded userName:password as the value. - If authMethod is HMAC, Walmart passes an authentication header to the eventUrl using authHeaderName as the header key and HMACSHA256 of the complete response as the value, with clientSecret as the key. - If authMethod is OAUTH, Walmart makes a POST call to authUrl to generate a token with request body "grant_type=client_credentials" and headers: (1) Authorization header using authHeaderName as the key and Base64-encoded clientId:clientSecret as the value, (2) Accept: "application/json; charset=UTF-8", (3) Content-Type: "application/x-www-form-urlencoded; charset=ISO-8859-1", and (4) any custom headers provided in headers. The authUrl must return HTTP 200 with access_token and expires_in fields. When sending notifications to eventUrl, Walmart includes the access_token in headers using authHeaderName as the key and value "Bearer ", along with any custom headers provided in headers. [block:html] { "html": "\n \n" } [/block] # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Notifications Management", "version": "1.0", "description": "Notifications Management API" }, "x-readme": { "samples-languages": [ "shell" ], "proxy-enabled": false }, "servers": [ { "url": "https://marketplace.walmartapis.com", "description": "Production URL" }, { "url": "https://sandbox.walmartapis.com", "description": "Sandbox URL" } ], "security": [ { "basicScheme": [] } ], "paths": { "/v3/webhooks/subscriptions": { "post": { "tags": [ "Notifications" ], "summary": "Create subscription", "description": "Create one or more webhook subscriptions for event notifications by selecting an event type, event version, resource name, and providing a destination event URL. Use the Get Event Types API to retrieve available event types, versions, and resource names. Configure the eventUrl to receive notifications.\n\nURL authentication options\n- If authMethod is BASIC_AUTH, Walmart passes an authentication header to the eventUrl using authHeaderName as the header key and the Base64-encoded userName:password as the value.\n- If authMethod is HMAC, Walmart passes an authentication header to the eventUrl using authHeaderName as the header key and HMACSHA256 of the complete response as the value, with clientSecret as the key.\n- If authMethod is OAUTH, Walmart makes a POST call to authUrl to generate a token with request body \"grant_type=client_credentials\" and headers: (1) Authorization header using authHeaderName as the key and Base64-encoded clientId:clientSecret as the value, (2) Accept: \"application/json; charset=UTF-8\", (3) Content-Type: \"application/x-www-form-urlencoded; charset=ISO-8859-1\", and (4) any custom headers provided in headers. The authUrl must return HTTP 200 with access_token and expires_in fields. When sending notifications to eventUrl, Walmart includes the access_token in headers using authHeaderName as the key and value \"Bearer \", along with any custom headers provided in headers.", "operationId": "createSubscription", "parameters": [ { "in": "header", "name": "WM_SEC.ACCESS_TOKEN", "description": "Access token obtained from the Token API. This is required for authenticating requests to Walmart Marketplace APIs.", "required": true, "schema": { "type": "string" }, "example": "eyJraWQiOiIzZjVhYTFmNS1hYWE5LTQzM....." }, { "in": "header", "name": "WM_CONSUMER.CHANNEL.TYPE", "description": "A unique ID to identify the consumer request by channel. Use the Consumer Channel Type received during onboarding.", "required": false, "schema": { "type": "string" } }, { "in": "header", "name": "WM_QOS.CORRELATION_ID", "description": "A unique ID that identifies each API call and is used to track and debug issues. Use a randomly generated GUID for this ID.", "required": true, "schema": { "type": "string" }, "example": "b3261d2d-028a-4ef7-8602-633c23200af6" }, { "in": "header", "name": "WM_SVC.NAME", "description": "Name of the Walmart service being called.", "required": true, "schema": { "type": "string" }, "example": "Walmart Marketplace" } ], "requestBody": { "description": "Request body parameters for creating one or more subscriptions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "required": [ "eventType", "eventUrl", "eventVersion", "resourceName", "status" ], "type": "object", "properties": { "eventType": { "type": "string", "description": "Event type to subscribe to. For allowed values, refer to the Event Payload section or use the GET Event Types API." }, "eventVersion": { "type": "string", "description": "Version of the event type. For supported versions per eventType, refer to the Event Payload section or use the GET Event Types API." }, "resourceName": { "type": "string", "description": "Resource (functional category) that the event type is mapped to. For allowed values per eventType, refer to the Event Payload section or use the GET Event Types API." }, "eventUrl": { "type": "string", "description": "Destination URL where notifications are delivered." }, "authDetails": { "type": "object", "properties": { "authMethod": { "type": "string", "description": "Authentication method for the destination URL. Allowed values: BASIC_AUTH, OAUTH, HMAC." }, "userName": { "type": "string", "description": "Username used to access the destination URL (required for BASIC_AUTH)." }, "password": { "type": "string", "description": "Password used to access the destination URL (required for BASIC_AUTH)." }, "authHeaderName": { "type": "string", "description": "Header name used to pass the authorization value to the destination URL (for example, Authorization)." }, "authUrl": { "type": "string", "description": "OAuth server or token URL used when the authentication method is OAUTH." }, "clientSecret": { "type": "string", "description": "Client secret used with the OAuth server (OAUTH) or as key material for HMAC." }, "clientId": { "type": "string", "description": "Client ID used with the OAuth server when the authentication method is OAUTH." } }, "description": "Authentication details for accessing the destination URL, if the URL is protected." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional HTTP headers to include when delivering notifications to the destination URL. Use for custom authentication headers, tracking identifiers, or any other headers your endpoint requires." }, "status": { "type": "string", "description": "Status of the subscription. Allowed values: ACTIVE, INACTIVE. To create a subscription, use status = ACTIVE. Notifications are sent only when the subscription is ACTIVE." } }, "description": "Subscription object describing a single event mapping, destination URL, optional authentication, and status." }, "description": "Array of subscription definitions to create." } } }, "examples": { "sample1": { "value": { "events": [ { "eventType": "OFFER_UNPUBLISHED", "eventVersion": "V1", "resourceName": "ITEM", "eventUrl": "https://example.com/events", "status": "ACTIVE" }, { "eventType": "PO_CREATED", "eventVersion": "V1", "resourceName": "ORDER", "eventUrl": "https://example.com/orders", "status": "ACTIVE" } ] } }, "sample2": { "value": { "events": [ { "eventType": "OFFER_UNPUBLISHED", "eventVersion": "V1", "resourceName": "ITEM", "eventUrl": "https://example.com/events", "authDetails": { "authMethod": "BASIC_AUTH", "userName": "abc", "password": "test", "authHeaderName": "Authorization" }, "headers": { "X-Custom-Header": "my-value" }, "status": "ACTIVE" } ] } }, "sample3": { "value": { "events": [ { "eventType": "OFFER_UNPUBLISHED", "eventVersion": "V1", "resourceName": "ITEM", "eventUrl": "https://example.com/events", "status": "ACTIVE" }, { "eventType": "BUY_BOX_CHANGED", "eventVersion": "V1", "resourceName": "PRICE", "eventUrl": "https://example.com/orders", "authDetails": { "authMethod": "BASIC_AUTH", "userName": "abc", "password": "test", "authHeaderName": "Authorization" }, "headers": { "X-Custom-Header": "my-value" }, "status": "ACTIVE" } ] } }, "sample4": { "value": { "events": [ { "eventType": "OFFER_UNPUBLISHED", "eventVersion": "V1", "resourceName": "ITEM", "eventUrl": "https://example.com/events", "status": "ACTIVE" }, { "eventType": "BUY_BOX_CHANGED", "eventVersion": "V1", "resourceName": "PRICE", "eventUrl": "https://example.com/orders", "status": "ACTIVE" }, { "eventType": "PO_CREATED", "eventVersion": "V1", "resourceName": "ORDER", "eventUrl": "https://example.com/events", "status": "ACTIVE" }, { "eventType": "PO_LINE_AUTOCANCELLED", "eventVersion": "V1", "resourceName": "ORDER", "eventUrl": "https://example.com/events", "status": "ACTIVE" } ] } } } } }, "required": true }, "responses": { "200": { "description": "Successful Operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "event": { "type": "array", "items": { "type": "object", "properties": { "eventType": { "type": "string", "description": "Event type for which the subscription was created." }, "subscriptionId": { "type": "string", "description": "Unique identifier for the subscription. Use this ID to retrieve, update, or delete the subscription." }, "partnerId": { "type": "string", "description": "Partner ID of the seller who created the subscription." }, "eventVersion": { "type": "string", "description": "Version of the event type for which the subscription was created." }, "resourceName": { "type": "string", "description": "Resource (functional category) that the event type is mapped to (for example, ITEM, ORDER, PRICE)." }, "status": { "type": "string", "description": "Subscription status. Allowed values: ACTIVE, INACTIVE." }, "eventUrl": { "type": "string", "description": "Destination URL where notifications are delivered." }, "authDetails": { "type": "object", "properties": { "authMethod": { "type": "string", "description": "Authentication method for the destination URL. Allowed values: BASIC_AUTH, OAUTH, HMAC." }, "userName": { "type": "string", "description": "Username used to access the destination URL (required for BASIC_AUTH)." }, "password": { "type": "string", "description": "Password used to access the destination URL (required for BASIC_AUTH)." }, "authHeaderName": { "type": "string", "description": "Header name used to pass the authorization value to the destination URL (for example, Authorization)." }, "authUrl": { "type": "string", "description": "OAuth server or token URL used when the authentication method is OAUTH." }, "clientSecret": { "type": "string", "description": "Client secret used with the OAuth server (OAUTH) or as key material for HMAC." }, "clientId": { "type": "string", "description": "Client ID used with the OAuth server when the authentication method is OAUTH." } }, "description": "Authentication details for accessing the destination URL, if the URL is protected." }, "headers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Additional HTTP headers to include when delivering notifications to the destination URL. Use for custom authentication headers, tracking identifiers, or any other headers your endpoint requires." } } } } }, "description": "List of subscriptions created in response to the request." }, "example": { "events": [ { "eventType": "OFFER_UNPUBLISHED", "subscriptionId": "620b45a0-b321-11ea-ac13-1f88d6025b7d", "partnerId": "12300000359", "eventVersion": "V1", "resourceName": "ITEM", "status": "ACTIVE" } ] } } } } } } } } } ```