What problem does it solve?
It prevents broken or insecure VTEX marketplace order integrations by ensuring webhook/feed-driven order status events are validated, deduplicated, and handled across the full lifecycle.
Core Features & Use Cases
- Order status integration via Hook or Feed v3: Choose push-based Hook for real-time middleware or pull-based Feed v3 for controlled throughput, with Feed as a fallback during downtime.
- Secure, authenticated event handling: Validate VTEX webhook authentication (expected Origin.Account and Origin.Key plus configured headers) before processing any order event.
- Idempotent state processing across retries: Deduplicate events using the combination of OrderId + State + LastChange to avoid double fulfillment or duplicate downstream actions.
- Complete lifecycle coverage with safe fallback: Handle all possible order statuses (including Status Null) with a default logger path for unknown values so processing never crashes or stalls.
- Integration pattern for external systems: Use Hook notifications to trigger ERP/WMS/fulfillment updates by fetching full order details with GET /api/oms/pvt/orders/{orderId}.
Quick Start
Configure a VTEX marketplace order Hook with a FromWorkflow filter for the states you care about, then build an endpoint that validates Origin and headers, deduplicates by OrderId+State+LastChange, fetches the full order by ID, and responds with HTTP 200 within 5000ms.
