Test the Fulfillment Side Effect, Not Just the Webhook Response
A webhook handler can return a successful response twice and still create two warehouse pick tasks. An integration test should check the business side effect after a repeated delivery. This is a small runnable teaching example from YX Fulfillment, not a description of the company's production system. Delivery identity and business identity answer different questions Shopify's delivery…
The example provided by YX Fulfillment demonstrates the importance of testing more than just the webhook response when integrating with their fulfillment system. A successful webhook response does not guarantee the desired business outcome, such as creating a warehouse pick task. The code example in release-demo.cjs showcases how to handle duplicate deliveries and ensure that only the desired business side effects occur.
The key concepts covered in the example include:
1. Differentiating between the webhook delivery identifier and the event identifier, which is shared by deliveries associated with the same merchant action.
2. Using a delivery key to determine if a delivery has been handled and a business key to determine if the intended operation already exists.
3. Handling cases where the same release revision is requested multiple times, ensuring that only one pick task is created.
4. Rejecting cases where the quantity changes under the same release key, as this could indicate an order amendment that needs to be handled separately.
The example highlights several important considerations for production integrations:
1. Keeping request verification and business logic separate, with authentication and normalization of messages handled before processing.
2. Enforcing uniqueness in persistent storage and ensuring consistency across failures.
3. Implementing recovery paths for asynchronous processing, where the incoming message or outbox work needs to be committed before acknowledging durable acceptance.
4. Considering the impact of an external warehouse API, such as using its idempotency mechanism to avoid duplicate work.
The example concludes by suggesting a set of exercises to thoroughly test the integration, including scenarios like duplicate deliveries, multiple workers processing the same release, restarts, unknown SKUs, cancellations, and changed quantities under existing release keys. These tests should cover both the integration record and the resulting warehouse instruction to ensure the system behaves as expected in various situations.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
