Using the API: credentials, quotas and webhooks

Mint and rotate API credentials, read your request quota, check the call log, and register signed webhook endpoints — from the API pages in your account.

The MarketplaceHub API lets your own systems read and write your catalog, listings, price, quantity and orders without going through the app. You manage it from the sidebar under API, which has four pages: Logs, Request Throttling, Credentials and Webhooks.

This page covers those screens. For endpoints, request and response shapes, and the interactive explorer, see the API reference.

Create a credential

Open API → Credentials and fill in Create a credential:

1. Give it a Name you'll recognise later — e.g. "Warehouse sync". It is a label for you; it has no effect on access.
2. Tick the Permissions it needs. Grant only what that integration uses:
   • OrdersRead — Read orders
   • OrdersWrite — Confirm, cancel, refund and update orders
   • InventoryRead — Read products and listings
   • InventoryWrite — Create and update products, listings, price and quantity
   • MarketplacesRead — Read marketplace connections and their health
   • WebhooksWrite — Manage webhook subscriptions
3. Click Create credential.

Copy the client secret before you close the panel. It is shown once and never again — we store only a hash of it. If you lose it, rotate the credential to get a new one.

Only an account administrator can create, rotate or revoke credentials, and you may be asked to sign in again first. Other team members can see the list, so they can tell whether an integration exists, but cannot change it.

Rotate and revoke

Every credential row has two actions:

• Rotate issues a new secret and gives the old one a 7-day overlap — the row shows the exact cutoff, e.g. "Previous secret for mh_… stops working at … UTC". Both secrets work during the overlap, so you can deploy the new one on your own schedule instead of racing a cutover. Rotate on a schedule, and whenever a secret may have been exposed.
• Revoke switches the credential off immediately. Its status changes to Revoked and calls using it start failing at once. Revoked rows stay in the list as a record; they cannot be re-enabled, so create a new credential instead.

Request Throttling

Calls are rate limited per account. API → Request Throttling shows one row per endpoint you've called:

• Available Request Count — how much budget is left right now.
• Maximum Quota — the ceiling that budget refills toward.
• Restore Rate — how quickly it refills.
• Last Request Time — when you last called it.

The page is empty until your credentials have made some calls. Go over the limit and the API answers 429; back off and retry rather than looping, and the budget restores on its own.

Logs

API → Logs records the calls your credentials made — version, URL, content type, status and time. Filter by any column, and expand a row to see the request and the response it got back. This is the first place to look when an integration behaves unexpectedly: it shows what actually arrived, which is often not what the integration meant to send.

Webhooks

Webhooks push events to your systems as they happen, so you don't have to poll. Open API → Webhooks, enter an https:// URL reachable from the internet, tick the events you want, and click Add endpoint. As with credentials, this is administrator-only, and the signing secret is shown once — copy it before closing the panel.

The events available today:

• OrdersDownloaded — New orders were pulled from a marketplace
• ListingPublished — A batch of products finished publishing to a marketplace
• FeedOutcome — A marketplace reported problems processing a feed
• MarketplaceUnhealthy — A marketplace connection stopped working
• MarketplaceRestored — A marketplace connection started working again

Verifying a delivery

Every delivery is signed. Check the signature before you trust the body — your endpoint is a public URL, and anyone can post to it. Each request carries:

• X-MH-Signature — the signature to verify
• X-MH-Timestamp — when it was sent
• X-MH-Event — which event this is
• X-MH-Delivery-Id — a stable id for the delivery
• X-MH-Attempt — which attempt this is, from 1

The signature covers the timestamp and the body, so a captured delivery cannot be replayed later. Reject anything whose timestamp is more than 5 minutes old. The webhook reference has the exact scheme and a worked example.

When an endpoint stops responding

A failed delivery is retried six times, backing off 1 minute, 5 minutes, 15 minutes, 1 hour, 3 hours, 6 hours — roughly half a day in total. The row shows Failing (n/6) while that plays out, so you can see how close it is to being switched off.

After six consecutive failures the endpoint is Disabled and the row explains why. Fix the endpoint, then delete it and add it again — a disabled endpoint cannot be re-enabled in place. Deliveries on any row opens its recent attempts with the response each one got, which is usually enough to tell a wrong URL from an outage on your side.

Where to go next

• Getting started — exchange your credential for a token and make a first call.
• Conventions — paging, errors, idempotency.
• Full reference — orders, inventory, marketplaces and jobs, webhooks.