Comparing B2B and B2C eCommerce API Integrations
An eCommerce business connects its storefront to the systems that manage products, prices, inventory, orders, payments, and delivery. APIs, or application programming…
When you build a client that manages webhook subscriptions, its code must handle both the published API description and the responses the server actually sends. A resource contract describes what clients can observe: which fields an operation returns, how the server wraps them, what an update changes, and what clients should expect when the server sends events.
In version 2.2.8, three webhook tools expected fields at the top level, while Automox returned a webhook object inside a data envelope. As a result, the tools returned null for every field. That included a signing secret, which the server exposes only at certain points in its lifecycle. The fix unwrapped the response and kept a fallback for responses without the envelope, as recorded in the Automox MCP changelog.
Design webhook APIs to match the responses clients actually receive, and document and test those responses. Keep the contract for managing a webhook subscription separate from the contract for events sent to subscribers: the first describes a resource clients configure, while the second describes what a receiver processes.
The endpoint name alone does not specify the response shape: the server might return an object directly, wrap it in data, or use a different shape for a list. The client must follow the documented response for each operation.
The Automox MCP defect affected create_webhook, get_webhook, and update_webhook. Each tool tried to read fields from the top level of the response, so each field appeared as null when the server placed the object inside data. The failure was especially consequential for a one-time secret: a client that drops the value when processing the creation response cannot recover it through an ordinary read.
Document response examples for create, read, update, and list operations. State whether each response uses an envelope, and describe any supported alternate shape. In client code, unwrap only the shapes the API documents; an informal fallback should not hide an unexpected response from monitoring or tests.
The same rule applies to errors and delivery records. Clients need to know how the server represents a failed test delivery. They also need to know whether an error includes a status code and which fields identify a delivery. The Automox API coverage document lists delivery-log fields such as success, statusCode, error, durationMs, and timestamp. These fields help a client report what happened without treating a delivery record as the subscription itself.
An update method must tell clients what happens to fields they leave out. A full replacement overwrites the whole resource. A partial update changes only the fields included in the request. When a client leaves fields out of a partial update, the server should keep their existing values. The documentation should say that it does.
The Automox MCP changelog says update_webhook changed from PUT to PATCH because the operation supports partial updates. The project’s API coverage page also reports a discrepancy: the published API description specifies PUT, while the wrapper uses PATCH and the live API accepts it. Automox’s help page lists PATCH for webhook subscription management as well. That evidence points to documentation drift, not a universal guarantee about every environment. API owners should publish the supported method and semantics in one authoritative place; client authors should verify the method against the API version they use. For a closer look at update methods and error handling, see REST API naming and methods.
Secret handling also needs an explicit lifecycle. The API should state which operation returns a signing secret, whether a later read can retrieve it, and what happens to the previous secret during rotation. The Automox changelog describes the secret as available only at creation, while the project’s API coverage says secret material is surfaced on create and rotate but omitted from reads. Because those descriptions do not say exactly the same thing, document and test the behavior for both creation and rotation rather than assuming one operation’s rules apply to the other.
Tell users to save the secret from the server response, and explain what to do if they lose it. Test that create and rotate responses expose the expected value and that ordinary reads do not. Avoid logging secret-bearing responses.
A webhook subscription is a resource users configure. It has an endpoint and selected event types, and users can read or change its settings. A delivered event tells the receiver that something happened. It may include a resource snapshot, a resource identifier, or both. The contract should define which.
A thin event carries identifiers or brief details about a change. The receiver fetches the current resource from the API when it needs more information. A full event carries more event data, so the receiver can act without making another API request. If a full payload represents historical state, say whether that state reflects the event time or some later point. The Automox sources reviewed here establish that subscription and delivery-management operations exist, but they do not establish whether event payloads are thin, full, or historical snapshots. API designers should state that choice rather than leave consumers to infer it.
Treat each event name as an identifier for a documented payload schema. Explain the event’s purpose and include examples. Document its required and optional fields and resource identifiers, then state the compatibility rules. Automox’s patch-result help page names policy.non_compliant for the described event and warns that older documentation may show system.patch.failed. That example shows why an event catalog needs active maintenance: a stale name can leave a valid-looking subscription listening for the wrong event.
Schema changes need a stated policy too. For example, Supabase documents a version prefix in event types and tells consumers to ignore unrecognized fields when new fields are added. That is Supabase’s policy, not a general webhook rule. Each provider should specify which changes require a new event or schema version, whether unknown fields are safe to ignore, and how long older versions remain available.
The subscription API and event-delivery API have different operational questions. A subscription client needs clear limits and a way to fetch every result. A receiver needs to know how the provider signs messages, retries failures, and identifies duplicates.
For paginated results, state the maximum number of items per page, how clients request the next page, and what any count measures. Make clear when a count covers only the current page rather than all matching resources. The Automox MCP changelog records list-input bounds of 1 to 500 for limit and a maximum cursor length of 2,000 characters. Those are documented bounds for that project’s wrapper, not defaults that other APIs should adopt. A client should follow the target API’s own limits and continue until the server indicates there are no more results. See pagination and webhook contracts for related design considerations.
For delivery, document the signature format and verification method, retry schedule, timeout, ordering guarantees, and duplicate-delivery behavior. The Standard Webhooks specification recommends signed messages, delivery identifiers, and retries with exponential backoff and jitter. Those recommendations do not establish Automox’s delivery behavior; the available Automox sources do not specify its retry schedule, signature headers, timeout, or duplicate guarantees.
A receiver should check each signature with the provider’s documented method and secret. When the provider supplies a stable identifier, the receiver should use it to recognize duplicate deliveries. It should acknowledge messages promptly and handle slow work asynchronously. If the event contract directs the receiver to fetch current state, use the event’s stable resource identifier for that read. For failures that need another delivery attempt, define the receiver’s response behavior from the provider’s documented rules; webhook retry strategies covers the design trade-offs.
The subscription contract should define URL validation because those rules determine which endpoints the service accepts. The Automox changelog records HTTPS requirements and later defenses against private or metadata destinations. It also records moving DNS resolution to a thread pool so validation would not stall concurrent asynchronous calls. Document rejected URL conditions and the resulting errors, and test validation against the security boundary the service intends to enforce.
Tests should use realistic HTTP responses, not just internal objects that already have the expected shape. The 2.2.8 defect passed the wrong assumption into three tools; a wire-level fixture with the data envelope would have exposed the mismatch.
For each operation, check both the result the client receives and the HTTP status. Include tests for the documented envelope, any explicitly supported unwrapped response, create and rotate secret behavior, reads that omit secrets, partial updates that preserve omitted fields, and empty or multi-page lists. Test successful and failed delivery records, along with unknown event types. Test additional event fields when the compatibility policy allows them.
When the published specification and live behavior disagree, record the exact method or response shape that the client observed and confirm which API version it applies to. Do not silently turn one observed response into a general contract. A contract test should fail when the service changes in a way that would break clients, while the documentation should tell users how to interpret the change.
Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.
Take a look at vroni.com