Marketplace webhooks
Marketplaces and their webhook contracts
Each marketplace has its own webhook auth + payload format. Sumeru abstracts these — but if you're building a parallel integration that mirrors what we do, here's the contract per channel.
| Marketplace | Auth | Format |
|---|---|---|
| Amazon | SNS topic subscription + signature verify | SNS message envelope |
| eBay | HMAC-SHA256 of body | JSON event |
| Etsy | Verification challenge + bearer token | JSON event |
| TikTok Shop | x-tts-signature HMAC | JSON event |
| Walmart | WM_SEC.AUTH_SIGNATURE HMAC | JSON event |
| Flipkart | Bearer token + body HMAC | JSON event |
Topic catalog (cross-marketplace)
Each marketplace exposes some subset of these:
| Topic | Sumeru use |
|---|---|
| Order created | Import to Shopify orders/create |
| Order updated | Status change tracking |
| Order cancelled | Reverse fulfillment |
| Inventory low | Sync with Shopify inventory |
| Listing approved/rejected | Catalog status |
| Pricing changed (rare) | Detect external changes |
Per-marketplace payloads
Amazon (SNS)
Amazon Marketing Stream + SP-API events come via Amazon SNS:
{
"Type": "Notification",
"MessageId": "...",
"TopicArn": "arn:aws:sns:us-east-1:...:sumeru-orders",
"Message": "{\"event_type\":\"ORDER_STATUS_CHANGE\",...}",
"Signature": "...",
"SigningCertURL": "https://sns.us-east-1.amazonaws.com/..."
}
Verification: validate signature against AWS-published cert.
Sumeru SNS subscriber endpoint handles confirmation
(SubscriptionConfirmation type) automatically.
eBay (HMAC)
eBay Notifications POST with HMAC body:
Header: X-EBAY-SIGNATURE: <hex>
Body: JSON event
Verification:
function verifyEbayWebhook(body, signature, devId) {
const expected = crypto
.createHmac('sha1', devId)
.update(body)
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expected)
);
}
Etsy
Two-step:
- Challenge: Etsy posts verification token; we echo back.
- Events: Bearer token in
Authorizationheader per event.
TikTok Shop
Header: x-tts-signature: <hex>
Body: JSON event
HMAC-SHA256 of body with shop secret.
Walmart
Header: WM_SEC.AUTH_SIGNATURE: <hex>
Header: WM_SEC.TIMESTAMP: <unix>
Header: WM_SEC.KEY_VERSION: <int>
Body: JSON event
Composite signature includes timestamp + body. Replay protection via timestamp window.
Flipkart
Header: Authorization: Bearer <static-token>
Header: X-Flipkart-Signature: <hex>
Body: JSON event
Common processing
After verification + parse, all marketplace orders flow through the same import pipeline:
Common gotchas
"Marketplace webhook arrived but order didn't show up." Check the failures dashboard. Common causes:
- HMAC mismatch (auth issue)
- Inventory mismatch (e.g. order for SKU we don't have)
- Customer match failed (no email in payload)
"Same order appears twice in Shopify." Marketplace retried; idempotency key wasn't matched. Check event ID dedup.