Test the Fulfillment Side Effect, Not Just the Webhook Response

Tom — Sat, 31 Oct 2026 08:29:09 +0000

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 verification guide explains that webhook deliveries can repeat. It distinguishes the webhook delivery identifier from the event identifier shared by deliveries associated with the same merchant action.

For HTTPS delivery, authenticate the request before trusting its identifiers or payload. Keep request verification separate from the example below, which starts with an already authenticated, normalized message.

A delivery key answers whether this delivery has been handled. A business key answers whether the intended operation already exists. For a warehouse release, that second key may combine the store, order and an explicitly approved release revision. The right revision rules depend on whether the business supports split releases, amendments and cancellations.

Do not invent a new release revision merely because a delivery is retried.

A small test that can catch duplicate work

Save this as release-demo.cjs and run node release-demo.cjs.

const assert = require('node:assert/strict');

const deliveries = new Set();
const pickTasks = new Map();

function acceptRelease(message) {
  const { shop, deliveryId, orderId, releaseRevision, sku, quantity } = message;
  assert.ok(shop && deliveryId && orderId && releaseRevision && sku);
  assert.ok(Number.isSafeInteger(quantity) && quantity > 0);

  const deliveryKey = JSON.stringify([shop, deliveryId]);
  const businessKey = JSON.stringify([shop, orderId, releaseRevision]);
  const proposed = { sku, quantity };

  if (pickTasks.has(businessKey)) {
    // Same operation with different contents needs a decision, not another pick.
    assert.deepEqual(pickTasks.get(businessKey), proposed);
    deliveries.add(deliveryKey);
    return 'existing';
  }
  if (deliveries.has(deliveryKey)) throw new Error('Delivery state is inconsistent');

  pickTasks.set(businessKey, proposed);
  deliveries.add(deliveryKey);
  return 'created';
}

const request = {
  shop: 'example-store', deliveryId: 'delivery-a', orderId: 'order-17',
  releaseRevision: 'approved-1', sku: 'POUCH-BLUE', quantity: 2
};
assert.equal(acceptRelease(request), 'created');
assert.equal(acceptRelease(request), 'existing');
assert.equal(acceptRelease({ ...request, deliveryId: 'delivery-b' }), 'existing');
assert.equal(pickTasks.size, 1);
assert.throws(() => acceptRelease({ ...request, quantity: 3 }));
assert.equal(pickTasks.size, 1);
console.log('Repeated deliveries created one unchanged pick task.');

The changed-payload test matters. Silently accepting a different quantity under the same release key can conceal an order amendment. The example rejects that conflict so the workflow has to resolve it deliberately.

What this demonstration leaves out

The in-memory collections are deliberately limited. They do not survive a restart, coordinate multiple workers, validate SKU mappings or call a warehouse service. A successful run does not prove a production integration is ready.

In a durable design, enforce uniqueness in persistent storage and make the delivery record and intended business operation consistent across failures. If processing is asynchronous, commit the incoming message or outbox work before acknowledging durable acceptance. A process crash between recording a delivery and recording its work needs an explicit recovery path.

An external warehouse API adds another boundary. Use its idempotency mechanism if available. If a release request times out after it may have been accepted, look up the existing release before sending another one. A local database transaction cannot roll back a parcel already released by an external system.

Add the cases a warehouse operator will encounter

Exercise a duplicate delivery, two workers racing on one release, a restart after persistence, an unknown SKU, a cancellation after acceptance and a changed quantity under an existing release key. Check both the integration record and the resulting warehouse instruction.

For a store connecting to a fulfillment provider, the useful acceptance question is concrete: after the same approved release reaches the integration twice, how many pick tasks exist, and how can an operator prove which one belongs to the order?

Testing repeated order events before warehouse release. Illustrative scene.

DEV Community: Tom

Test the Fulfillment Side Effect, Not Just the Webhook Response

Delivery identity and business identity answer different questions

A small test that can catch duplicate work

What this demonstration leaves out

Add the cases a warehouse operator will encounter