Overview
Endpoints that receive the account events, and the rules that apply to all of them.
An endpoint is a URL of your system that receives our events: an account connected, disconnected, a job finished. Each event arrives as a signed POST. You can register as many endpoints as you want and pick the event types of each one.
Which event each change sends and how a delivery changes state, as diagrams: States and events.
How to verify the signature and handle retries: Receiving webhooks.
Endpoints
| Method | Path | What it does |
|---|---|---|
GET | /v1/webhooks/event-types | List event types |
POST | /v1/webhooks/endpoints | Register an endpoint |
GET | /v1/webhooks/endpoints | List endpoints |
GET | /v1/webhooks/endpoints/{id} | Get an endpoint |
PATCH | /v1/webhooks/endpoints/{id} | Update an endpoint |
DELETE | /v1/webhooks/endpoints/{id} | Delete an endpoint |
POST | /v1/webhooks/endpoints/{id}/rotate-secret | Rotate secret |
GET | /v1/webhooks/deliveries | List deliveries |
GET | /v1/webhooks/deliveries/{id} | Get a delivery |
POST | /v1/webhooks/deliveries/{id}/redeliver | Redeliver |
All of them require Authorization: Bearer mk_your_api_key. See Authentication.
The secret
Creation returns the secret (whsec_...) only once. You use it to verify the signature of every delivery, in the X-Marketapi-Signature header. It never comes back in another response: if you lose it or it leaks, rotate it: the new one shows up once, and the old one stops working at once.
Events
| Event | When | data fields |
|---|---|---|
connection.created | A seller connected a marketplace account. | connection, linkSessionId, syncJobId |
connection.updated | A connection changed: the seller connected the same account again, or it failed for good (`active` to `error`). | connection, previousStatus, syncJobId |
connection.revoked | A connection was revoked: by you, or by the marketplace (the seller removed the access, or the marketplace refused to renew it). | connection |
link_session.completed | A seller clicked Finish on a link session. | linkSession |
seller.created | A seller was created. | seller |
seller.updated | A seller's name or external ID changed. | seller |
seller.deleted | A seller was deleted. | seller |
product.created | A reusable product base was created. | product |
product.updated | A reusable product base changed locally. | product |
product.archived | A reusable product base was archived. | product |
variant.created | A sellable product variant was created. | variant |
variant.updated | A sellable product variant changed locally. | variant |
variant.archived | A sellable product variant was archived. | variant |
inventory.movement_created | An immutable inventory movement was recorded. | movement, balance, publicationJobId |
inventory.published | Current inventory quantity was published to a listing binding. | listingId, bindingId, variantId, quantity |
warehouse.created | A warehouse was created, by you or together with its seller (the default one). | warehouse |
warehouse.updated | A warehouse changed: its name, its external ID, whether it is the seller's default, or it was reactivated. | warehouse |
warehouse.archived | A warehouse was archived. | warehouse |
marketplace_product.created | A marketplace product (content shared by offers) was created locally or imported. | marketplaceProduct |
marketplace_product.updated | A marketplace product changed: its local content, its variations, or what the marketplace shows. | marketplaceProduct, behavior, jobId |
listing.created | A local marketplace listing draft was created. | listing |
listing.updated | A listing or its synchronization changed. | listing, behavior, jobId, bindingId |
listing.deleted | A local listing record was removed by an explicit choice. | listing, publication |
listing.status_changed | The marketplace status of a listing or of one of its lines changed. | listingId, connectionId, marketplaceProductId, source, listing, bindings |
listing.external_changed | A marketplace listing change was observed. | listing, behavior, recordUpdated, productId, variantIds, observed |
listing.conflict_created | A conflict was opened: the marketplace changed a group of the listing that also had local changes not yet published. | listingId, conflictId, group, paths |
listing.conflict_resolved | A listing conflict was resolved. Only the local desired data changed: nothing was published. | listingId, conflictId, group, paths, resolution |
asset.ready | An asset passed its checks and can be used (`ready`). | assetId, class, status |
asset.failed | An asset was refused or its upload was never completed (`failed`). Its file was discarded. | assetId, class, status, failureReason |
order.created | An order appeared in marketapi: by import, reconciliation or a marketplace notification. | order |
order.updated | An order changed: its status, totals, lines, payments or the link of a line. | order |
order.cancelled | An order was cancelled. This event is sent alone: the cancellation does not produce `order.updated`. | order |
job.completed | A job finished with every item done. | job |
job.partially_completed | A job finished with some items failed. | job |
job.failed | A job failed. | job |
events: ["*"] receives all of them, including future ones. The * goes alone: mixing it with specific types gives 400.
Deliveries
Each event becomes one delivery per subscribed endpoint. If your endpoint does not answer 2xx within 10 seconds, we try again after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h; after the 8th attempt the delivery is failed. The log keeps the outcome of the last attempt of each delivery.
The same event can arrive more than once (a late answer, a redelivery). Deduplicate on the id of the body; X-Marketapi-Delivery-Id changes on every delivery.
A paused endpoint
enabled: false pauses the endpoint: new events skip it, and its pending deliveries fail without a call. enabled: true turns it back on; events from the paused time are not resent.