Wait for Signal Step

Pause a scenario until a manual action is done; event or callback arrives.

What it does

• Suspends the scenario at a specific point until a matching signal (event, callback, or message) is received.
• Uses a correlation key (for example, order ID, reference number, external job ID) so the right signal resumes the right scenario instance.
• Can define timeouts and fallback paths so the flow does not wait forever if the signal never arrives.
• Produces an output object with signal payload (for example, approval decision, external status, webhook body) that you can use in later steps.

When to use it

• When a manual approval is needed.
• When part of your process is asynchronous and controlled by an external system or person (for example, warehouse confirmation, payment provider callback, marketplace webhook).
• When you want to avoid polling an external system in a loop and instead react to a single, authoritative event.
• When you need to model long‑running business workflows with explicit “waiting” states (for example, “waiting for customer response”, “waiting for fulfillment creation”, “waiting for manual review”).

How to configure

• Signal type / channel

  • Choose what kind of signal this step expects (for example, approval, warehouse_reservation_confirmed, payment_captured).
  • Use a consistent naming scheme so integrations and other scenarios can emit compatible signals.

• Correlation key

  • Map one or more fields that uniquely identify the business object you are waiting on:
    • Examples: data.orderId, steps.create_reservation.outputs.reservationId, data.paymentReference.
  • Make sure the external system (or scenario that sends the signal) can reproduce the same key so the signal finds the right waiting instance.

• Timeout & fallback

  • Set a maximum wait time (for example, minutes, hours, or days) according to your business SLA.
  • Define what happens on timeout:
    • Continue on a timeout branch (for example, cancel reservation, send alert, move to exception queue).
    • Raise an Error step for strict flows that must not proceed without the signal.
  • Align timeout values with business expectations (for example, warehouse confirmations may take hours; PSP callbacks usually minutes).

• Output mapping

  • The signal’s payload becomes available as step outputs (for example, steps.wait_for_warehouse.outputs.signal).
  • Map only the fields you actually need downstream (status, timestamps, decision, reference IDs) to keep data small and clear.

Business‑logic considerations

• Idempotency and duplicates

  • External systems may send the same signal more than once; design your flows and correlation keys so that:
    • Only the first matching signal resumes the waiting instance.
    • Later duplicates are either ignored or logged, not re‑processing the business action.

• Ownership of the “truth”

  • Treat the signal as the source of truth for the state you are waiting on (for example, “shipment created”, “payment captured”).
  • Avoid mixing signal‑driven updates with parallel polling or manual overrides unless you have clear rules for which wins.

• Timeout vs. business escalation

  • Timeouts should represent a real business decision point, not just a technical default.
  • For example: “If warehouse has not confirmed within 24h, release reserved stock and notify support” rather than silently continuing.

• Where not to use it

  • Do not use Wait for Signal for short, purely technical delays (like “sleep 5 seconds”) or for steps that can complete synchronously via API.
  • Prefer it when the pause represents a meaningful state in the business process that stakeholders care about.

Typical patterns

• Approval flows

  • Scenario creates a draft action (refund, cancellation, bulk price change), sends a task to an approval system, then uses Wait for Signal until approved / rejected arrives.
  • Downstream branches apply different business rules based on the signal payload.

• Reservation and fulfillment

  • Reserve stock in WMS/ERP, then Wait for Signal confirming success/failure before updating marketplace stock or order status.
  • On timeout, automatically roll back or re‑route orders to another warehouse.

• Async payment and invoicing

  • Initiate payment, then Wait for Signal from the PSP summarizing the outcome.
  • Proceed to invoice and ship only after a positive signal; on failure or timeout, notify finance or reverse provisional actions.

• External long‑running jobs

  • Start an export, sync, or reconciliation job in an external system, store its job ID, then Wait for Signal with that job ID.
  • When the job finishes, the signal resumes the scenario, which continues with post‑processing or reporting.