- Record each exchange as a business event with a clear status.
- Separate receiving a message from completing the requested work.
- Retries must not create duplicate orders, customers or stock updates.
- Store enough context to investigate without copying sensitive data everywhere.
- Give operators a safe replay action and an escalation path.
The client could not operate an integration from HTTP logs
Orders, customers and stock cross the commerce–ERP boundary through webhooks, outbound calls and scheduled work. Medusa lets us implement those routes and workflows. A successful HTTP response still does not tell the client whether stock changed, an event was already handled or only part of a batch succeeded.
We built one structured journal for those directions. It stores the business outcome, direction, event kind, duration and safe diagnostic context. The Admin dashboard can then expose recent activity and silence without asking an e-commerce operator to search server logs. That visibility was a project feature in its own right, not incidental logging.
The invisible conversation between the shop and the ERP
An e-commerce platform and an ERP exchange many messages: a new order is ready for fulfilment, stock has changed, a customer was updated or a refund was accepted. These messages are often called webhooks. In plain language, a webhook is simply one system notifying another that something happened. When everything works, nobody notices. When it fails, teams see only the consequence: an order missing from the ERP or stock that no longer agrees with the website.
Ordinary server logs were a poor support tool for the client. They could disappear quickly, mix several customers together and describe technical exceptions without explaining the business action. The client needed each exchange to leave a small, searchable history: what event arrived, which business record it concerned, what the system tried to do, whether it succeeded and what the next safe action was.
Receiving a message is not the same as completing the work
A webhook endpoint often answers quickly with a successful HTTP response. That response usually means ‘I received your message’, not ‘the order is now fully processed’. The distinction matters. The message may be stored and processed seconds later. The ERP may be unavailable. Validation may reject the content. If dashboards treat receipt as completion, failures remain invisible until a human notices missing data.
We modelled separate stages: received, being processed, succeeded, waiting to retry and permanently failed. The exact labels are less important than the separation. Each status should answer a business question. Has the message reached us? Is work still expected? Did it change the target record? Will the system retry automatically? Does someone need to intervene? This turns an asynchronous technical process into an operational queue.
Create one timeline for every exchange
Each attempt records the event type, direction, source system, relevant order or product reference, time received, time completed and outcome. A shared correlation reference connects retries and related steps. Support can therefore open an order and see that Medusa sent it, the ERP rejected one field, a retry succeeded and no further action is required.
We deliberately do not copy complete customer or payment payloads into every log entry. Investigation needs identifiers, selected safe fields and a protected way to inspect deeper evidence when authorised. Retention is also a business decision. Keeping everything forever increases privacy and storage risk. Keep the smallest useful history for the period in which support, finance and engineering realistically investigate exchanges.
Retry without performing the business action twice
Messages are repeated in real systems. The sender may not receive the acknowledgement, a worker may crash after updating the ERP, or an operator may press replay. A repeated message must not create a second order or apply the same stock movement twice. The system needs a stable identity for the business action, not merely a timestamp for each technical attempt.
For example, ‘export order 123’ should have one durable operation identity. Every retry checks whether that operation already completed before doing it again. The history can contain several attempts while the business effect happens once. This turns replay from a dangerous emergency action into a controlled operating tool.
Give operators decisions, not stack traces
An operator view should group events by order, product or customer and use plain statuses. It can show the last safe error message, next retry time and number of attempts. A replay button should be available only when replay is safe and the user has permission. Permanent validation errors—such as an unknown product code—usually need data correction, not twenty automatic retries.
The interface also needs boundaries. Replaying an outgoing order export is different from reprocessing an incoming stock adjustment. Some actions affect money or fulfilment and require a reason or approval. Manual actions should be recorded with the operator and result. The aim is to let operations solve known problems while preserving a clear path to engineering for genuinely new failures.
Alert on business delay, not every technical noise
One failed attempt that succeeds thirty seconds later may not deserve an alert. An order that has not reached the ERP after ten minutes may block fulfilment. Monitoring should therefore use business expectations: age of the oldest unfinished order export, number of records waiting beyond the normal delay, repeated failures for one event type and unusual growth of the retry queue.
Useful dashboards show both volume and outcome. A hundred successful exchanges can hide one high-value order that is stuck, so operators also need searchable exceptions. Error messages should be grouped into actionable categories such as authentication, validation, unavailable dependency and unexpected internal failure. That makes trends visible and avoids teaching support to ignore a wall of identical alerts.
Our checklist for an observable integration
Can the team find every exchange related to one order? Are receipt and completion separate? Is the next automatic retry visible? Can a repeated message be recognised using a stable business identity? Are payloads reduced and protected? Does a permanent error stop retrying and explain what must be corrected? Is every manual replay authorised and recorded?
Finally, test the awkward cases: the ERP accepts the request but the response is lost; two identical notifications arrive together; processing stops halfway; a corrected record is replayed; and one broken event does not block the entire queue. Integration observability is successful when a non-developer can explain what happened and choose the next safe action without reading application logs.
Common questions
It is an automated message sent by one system to tell another that an event occurred—for example, that an order was created or stock changed.
Logs are designed for engineers and may be short-lived or fragmented. An operational history groups safe information around the business record and shows status, retries and next actions.
When the business action has a stable identity, the receiver can recognise completed work, and the operator understands whether the failure needs a retry or a data correction.