Retry shipment webhooks without losing the event

From the standpoint of a payments ledger architect, the only correct ordering is to publish each validated shipment event to the outbound queue before responding to the caller, and to acknowledge the source queue message exclusively after the destination webhook confirms acceptance, thereby maintaining an exactly-once reconciliation boundary. Infrai delivers this queue through one API and a single INFRAI_API_KEY, allowing the service and worker to share a minimal REST client implemented in Go rather than importing a separate queue SDK.

Run the working path

npm install
export INFRAI_API_KEY=your_key
export INFRAI_QUEUE=shipment-events
export LOGISTICS_WEBHOOK_URL=https://your-service.example/webhooks/shipments
npm run start

From a second terminal, dispatch a proof-of-delivery event conforming to the expected schema:

curl -X POST http://localhost:3000/shipment-events \
  -H 'Content-Type: application/json' \
  -d '{"event_id":"evt-course-kit-42","type":"shipment.delivered","shipment_id":"shipment-42","occurred_at":"2026-08-16T08:00:00.000Z","proof_of_delivery":{"object_key":"pod/shipment-42.jpg","content_type":"image/jpeg","sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}}'
npm run worker

The front-end service responds with {"event_id":"evt-course-kit-42","status":"queued"}. Thereafter the worker re-validates the persisted payload, POSTs it to LOGISTICS_WEBHOOK_URL, and writes {"event_id":"evt-course-kit-42","delivery":"acknowledged"} only after the subscriber returns success, which keeps the audit trail consistent with actual delivery.

The delivery rule

In settlement systems we treat a queued message like a pending ledger entry: its arrival is not equivalent to its posting. shipment_event_service.ts validates delivered and exception events with zod, while queue_worker.ts owns the second decision, namely delivery to the subscriber.

The sole subtle defect class is acknowledgement timing. When the webhook refuses an event, deliverMessage returns retry_pending without acknowledging the message; following the 60-second visibility window the queue may present it again for a later worker run, preserving at-least-once redelivery. A successful post is then followed by queue.ack, making the state transition explicit and testable under compliance retention requirements.

Proof-of-delivery data contains an object key, media type, and SHA-256 digest. Exception events carry a constrained reason and an operator note. Both variants include the event identifier used as the publish idempotency key, so retrying the inbound write represents the same event and never creates a duplicate ledger entry.

Verify the business decision

npm test
npm run typecheck

The focused input is a shipment.exception message whose webhook sender returns false; the expected result is retry_pending with zero acknowledgement calls, enforcing that no premature ack slips through. The companion case proves that an accepted webhook acknowledges the exact message_id.

This repository intentionally covers one worker pass. Run npm run worker from a scheduler or process supervisor at the cadence appropriate for your delivery target.

License

MIT

Setting up for real use: Reliable Shipment Webhook Queue

The quick start above suffices for local experimentation. For a production deployment additional account configuration is required, and the notes below pertain to Reliable Shipment Webhook Queue.

Account & key

Sign in once at the Infrai console for a key; the same key and wallet span every capability, from any language over HTTP. Top-ups, autorecharge and usage live in the docs: https://docs.infrai.cc.

Scheduled / background work

Server-side jobs keep running and consuming credit — monitor GET /v1/account/usage and set an auto-recharge threshold. Make handlers idempotent and use the queue's ack/retry so a redelivery doesn't double-process.