A supplier needs every order in its own system. How do you open Medusa without losing control?

The client problem

A marketplace can accept an order perfectly and still create hours of manual work for the supplier who must fulfil it. If that supplier runs an ERP, warehouse tool or order-management system, asking a person to copy every line from a portal is not an integration strategy. It is a recurring source of delay and transcription mistakes.

The tempting answer is “send a webhook”. The difficult part begins immediately afterwards. Each supplier may expose a different base URL, path, authentication header and health endpoint. Their receiving system must be able to prove that a payload really came from the marketplace. Your operations team needs to test the connection before a live order depends on it. And when the endpoint rejects an order, somebody needs enough evidence to diagnose the exchange.

We built a seller-specific outbound webhook capability around Medusa to solve that business problem. It turns a generic order event into a configurable supplier integration: scoped configuration, a stable order contract, signed payloads, safe secret rotation, sample dispatch and delivery telemetry.

The result is not “a POST request”. It is an integration surface that suppliers and marketplace operators can establish deliberately before the first real order arrives.

Start with the supplier's operating problem

A multi-vendor marketplace does not fulfil every order itself. The commercial transaction may happen in one platform while stock allocation, picking, shipment and invoicing continue in a supplier's own tools.

That creates a practical requirement: once an order is ready for supplier processing, the relevant supplier system needs the data in a form it understands. The payload normally includes the order reference, totals, currency, customer and delivery details, product identifiers, quantities and purchasing context such as the property concerned.

Email can bridge the gap during a pilot, but it does not scale gracefully. It forces the supplier to interpret an unstructured message, re-enter data and decide whether an update is a duplicate. A shared portal is better, yet it still asks the supplier to work outside its normal operating system.

An outbound webhook allows the marketplace to push a structured event at the moment its own order lifecycle says the supplier can act. The architecture therefore begins with a business event, not with an arbitrary HTTP route.

Give every supplier an explicit integration contract

We modelled webhook configuration as a seller-owned resource. A configuration records which seller it belongs to, its name, base URL, delivery path, optional ping path and method, activation state, custom headers, signing secret and latest test result.

That separation matters. A marketplace may work with one supplier that accepts a standard bearer token, another that requires a tenant header and a third whose production webhook lives below a dedicated path. Hard-coding those differences in the order subscriber would turn every onboarding into a deployment.

Configuration lets an operator establish the contract without changing the marketplace code. The delivery URL can be composed from a stable base and a webhook-specific path. A separate ping path supports connection checks when the supplier does not want a sample order sent to its normal ingestion route.

Activation is explicit too. A configuration can exist while it is being prepared or investigated without receiving live events. That gives operations a safe sequence: create, configure, test, activate.

Resolve the supplier from the order, not from user input

The event handler receives an order identifier. It then resolves the seller associated with that order and loads only active webhook configurations for that seller.

This is a fundamental tenant boundary. The caller does not choose which supplier receives the event, and the payload is not broadcast to every configured integration. The commerce relationship already recorded on the order determines the destination set.

If no seller can be resolved, or that seller has no active webhook, the handler stops. That behaviour is safer than guessing. In a marketplace, sending an order to the wrong supplier is a commercial and confidentiality failure, not a minor technical inconvenience.

The same principle applies to the property context added to the payload. We prefer the explicit order-to-property relationship. During the short period before that relationship is available, the implementation can fall back through customer-property links while checking that requested property context belongs to the customer. Context is derived from trusted commerce relationships rather than copied blindly from metadata.

Design a stable payload for the receiving system

Passing Medusa's entire internal order object would tightly couple every supplier to implementation details that can change as the platform evolves. We instead reshape the order into a deliberate public contract.

The top level carries stable commercial facts: identifiers, status, currency, totals, customer reference, shipping address, property context and creation time. Each line contains quantity, fulfilled quantity, price and total information plus product, variant and supplier-facing SKU data.

This translation layer is where marketplace concepts meet the supplier's operational vocabulary. In the project, one receiving contract required a two-character unit-of-measure code. The marketplace data could contain forms such as a quantity and unit together, so the outgoing adapter normalised that value rather than forcing the ERP to understand internal catalogue conventions.

That is the architectural value of the webhook boundary: Medusa remains the commerce engine, while a small adapter publishes the exact business document the downstream system needs.

Sign the exact bytes that leave the platform

A supplier should not trust an order merely because it arrived at a secret-looking URL. URLs leak into logs, browser history and configuration systems. Source IP allow-lists can help, but they do not prove the integrity of a particular body.

For each configuration, the platform creates a dedicated random secret. Before delivery, it serialises the event envelope and computes an HMAC-SHA256 signature over those exact bytes. The signature, event name and webhook identifier travel in dedicated headers.

The supplier can calculate the same signature with its copy of the secret and compare the result using a timing-safe operation. If a character in the body changes, the signatures differ. This authenticates the sender and protects payload integrity without placing the secret itself in the request.

The important operational rule is simple: verify the signature against the raw request body before parsing or transforming it. Re-serialising JSON may change whitespace or key order and produce a different byte sequence even when the data appears equivalent.

Treat custom headers as configuration, not code

Some supplier endpoints need additional credentials or routing values. The webhook configuration accepts a bounded list of key-value headers, validates their shape and applies them before the standard content, event, identifier and signature headers.

This avoids a new software release for each ordinary integration variation. It also keeps those values attached to the supplier configuration rather than scattered through environment variables or conditionals in the subscriber.

The marketplace still owns the standard contract. Content type, event name, signing header and webhook identity are produced consistently. Customisation exists around that core, not instead of it.

For a production system, configuration access must be restricted to authorised administrators, secrets must not be echoed casually in list responses and outbound destinations need the same network policy applied to any server-side request. Configurability is useful only when it remains inside a controlled administrative boundary.

Test the contract before a live order depends on it

A “Save” button cannot prove that the other system is reachable or understands the payload. We added an explicit sample-delivery action.

It builds a representative order event, signs it with the webhook's current secret and sends it through the same URL and header construction used by live delivery. The response records success or failure, status code, response time and test timestamp.

This gives both teams a concrete onboarding loop. The marketplace operator configures the endpoint. The supplier checks its signature verification and mapping. A sample is sent. Both sides can correct the contract before activation.

A separate ping mechanism is useful for lightweight health checks, but it should not replace the signed sample. A server returning 200 on a health route proves reachability; it does not prove that the production ingestion path accepts the event schema.

Make secret rotation an ordinary operation

Shared secrets eventually need to change: a credential may be exposed, a supplier may rotate its integration environment, or security policy may require periodic renewal.

The administration surface therefore includes a regeneration action rather than requiring a database edit. Rotation produces a new signing secret for that webhook configuration.

The receiving team still needs a coordinated transition. The practical sequence is to generate the new secret, deliver it through an approved channel, update verification on the supplier side, send a sample and then confirm the live path. If uninterrupted rotation is required, the next evolution is a short overlap window in which the receiver accepts both old and new key identifiers.

The important design choice is that rotation belongs to the product's operating model. It is not an emergency procedure invented after a credential problem.

Capture enough evidence to diagnose rejection

Outbound integrations fail in ordinary ways. The endpoint times out. DNS fails. The server responds with a validation error. Authentication is stale. A schema change exposes an assumption on either side.

The delivery path records the target configuration, event, order reference, HTTP status, elapsed time, body size and a bounded response snippet. Non-success responses and request exceptions become observable backend events. A timeout prevents one unresponsive receiver from occupying the worker indefinitely.

The response snippet is deliberately truncated. It can reveal a useful message such as “unknown unit code” without allowing an uncontrolled downstream response to flood logs. Operational telemetry should also redact secrets and minimise customer data.

This evidence changes support conversations. Instead of “the order did not arrive”, the team can establish which endpoint was called, how long it took, what status it returned and which event was involved.

Separate commerce acceptance from downstream delivery

The marketplace should not pretend that a remote supplier system is part of the same database transaction as Medusa. The commerce event exists locally; delivery is a separate integration effect that can fail.

In the implementation we inspected, active webhooks for a seller are dispatched in parallel and failures are captured rather than rewriting the accepted order. That protects the commerce path from a slow supplier endpoint, but it also defines the next operational question: how failed deliveries are retried or replayed.

A mature extension can persist one delivery record per event and endpoint, use an idempotency identifier, retry temporary failures with bounded backoff and expose a replay control. The receiver should deduplicate on that stable event identity. Those capabilities turn delivery from best-effort notification into a recoverable integration queue.

They should be introduced explicitly rather than hidden behind the word webhook. Signing proves authenticity; it does not guarantee delivery. A 200 response proves acceptance by the remote HTTP service; it does not prove warehouse fulfilment.

What the supplier receives

From the supplier's perspective, the integration becomes predictable:

1. The marketplace documents one versioned order event.
2. The supplier receives a dedicated endpoint configuration and signing secret.
3. Both teams validate the contract with a signed sample.
4. Only that supplier's relevant orders are sent.
5. Every request carries an event name, webhook ID and body signature.
6. Failures produce diagnostic evidence for operations.

That is far more useful than claiming that Medusa “supports webhooks”. Medusa supplies the commerce events and extension points. The marketplace architecture turns them into a supplier-specific operating capability.

The wider lesson for a B2B marketplace

Integrations should be treated as products with configuration, trust, testing and support surfaces. The HTTP call is the smallest part.

We chose Medusa because its modular event model lets us keep order ownership inside the commerce engine while adding the exact supplier contract the business requires. One supplier can receive a signed order payload today; another adapter can translate the same business event into a queue or ERP connector tomorrow.

That is what extensibility should deliver. The marketplace does not force every partner into its internal model, and it does not surrender control of the order lifecycle to a remote endpoint. It creates a deliberate boundary between the two.

If your suppliers still re-enter marketplace orders manually, WeAreSouk can design the Medusa event, signing, configuration and recovery contract that connects commerce to their operating systems.