vtex-io-events-and-workers

Design VTEX IO event handlers with idempotency and retry-safe background processing.

Updated Mar 27, 2026
One-click install
npx skills add https://github.com/exilonX/ap2 --skill vtex-io-events-and-workers-exilonx
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: vtex-io-events-and-workers
Source: https://github.com/exilonX/ap2/tree/main/.agents/skills/vtex-io-events-and-workers
Command: npx skills add https://github.com/exilonX/ap2 --skill vtex-io-events-and-workers-exilonx

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you design VTEX IO services that process events and background work reliably, even when deliveries are duplicated or retried.

Core Features & Use Cases

  • Idempotent Event Handlers: Prevent inconsistent side effects when the same event is delivered multiple times.
  • Retry-Safe Background Processing: Make expensive work resilient to retries by recording processing state and handling failures explicitly.
  • Correct Async Contracts: Keep handlers independent from HTTP-only assumptions by using explicit async payload inputs instead of request-bound context.

Use Case: You receive an order-created broadcast in your app and need to sync it with an external system without double-sending or blocking the checkout request path.

Quick Start

Ask the AI to help you implement an idempotent VTEX IO event handler that processes broadcast events safely and records success/failure for retries.

Frequently Asked Questions about vtex-io-events-and-workers

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I make VTEX IO event handlers idempotent for replayed deliveries?

To make VTEX IO event handlers idempotent, you must explicitly record durable processing state and handle partial failures to prevent inconsistent side effects when duplicate broadcast events are delivered.

What is the best way to process background jobs in VTEX IO without blocking the request path?

The best way to process background jobs in VTEX IO without blocking requests is using async event handlers and workers, which isolate expensive work from the main request path and ensure retry-safe processing.

Why does my VTEX IO background worker duplicate side effects on retry?

VTEX IO background workers duplicate side effects on retry because delivery is at-least-once. Without explicit handler idempotency and durable processing state, replayed events trigger duplicate external syncs.

Do I need explicit async input contracts for VTEX IO event handlers?

Yes, you need explicit async input contracts for VTEX IO event handlers. Using explicit async payload inputs instead of request-bound context keeps handlers independent from HTTP-only assumptions and ensures stable async processing.

How do I record partial-failure in VTEX IO batch processing?

To record partial-failure in VTEX IO batch processing, you implement clear partial-failure recording within your event handlers, ensuring durable processing state tracks which items failed to allow safe targeted retries.

Can I use VTEX IO workers for cross-service fan-out integration?

Yes, you can use VTEX IO workers for cross-service fan-out integration. They support event-driven integrations and delayed jobs, requiring durable processing state to manage at-least-once delivery safely.