EventWait event-wait

When to Use

• Payment webhook confirmation: After creating an invoice, wait for a payment.completed event correlated on the invoice ID. The workflow thread is freed — no polling. When the payment provider posts the webhook, the event bus publishes the event and the workflow resumes with the full payment payload.
• External async job callback: Trigger a long-running external job (image processing, report generation, ML inference) then wait for a job.finished event correlated on the job ID returned by the trigger call. Resume only when the job reports completion.
• Cross-workflow signaling: A parent workflow suspends waiting for an event. A separate child or sibling workflow publishes the event when its own processing completes. EventWait is the coordination mechanism between independently running workflows.
• IoT or hardware trigger: A manufacturing workflow starts a machine operation then waits for a sensor.threshold.reached event correlated on the device ID. The workflow only resumes when the physical machine reports the condition.
• User action gate: Workflow sends an email with a confirmation link. When the user clicks the link, an endpoint publishes a user.confirmed event. The waiting workflow resumes, verifies the event payload, and proceeds to activate the account.

Configuration

Sample Configuration

Wait for a payment webhook correlated on invoice ID

{
  "event_name": "payment.completed",
  "correlation_id": "{{ $output.createInvoice.invoiceId }}",
  "correlation_field": "invoiceId",
  "timeout_seconds": 86400,
  "event_source": "webhook"
}

Wait for a Kafka event on a specific topic

{
  "event_name": "order.shipped",
  "correlation_id": "{{ $json.orderId }}",
  "timeout_seconds": 259200,
  "event_source": "kafka",
  "kafka_topic": "logistics.shipment.events"
}

Cross-workflow approval signal (indefinite wait)

{
  "event_name": "approval.decision",
  "correlation_id": "{{ $var.approval_request_id }}",
  "timeout_seconds": 0,
  "event_source": "internal"
}

IoT sensor event with payload filter

{
  "event_name": "sensor.threshold.reached",
  "correlation_id": "{{ $json.deviceId }}",
  "correlation_field": "deviceId",
  "timeout_seconds": 3600,
  "filter_expression": "event.temperature > 80 && event.unit == 'celsius'"
}

Validation Errors

Output / Execution Ports

waiting Port — Output Fields (fires immediately on suspension)

success Port — Output Fields (fires when event received)

Sample Output

waiting port output (fires immediately)

{
  "event_wait": {
    "id": 44192,
    "event_name": "payment.completed",
    "correlation_key": "payment.completed:INV-20260526-0041",
    "timeout_at": "2026-05-27T14:22:00Z"
  }
}

success port output (fires when event arrives)

{
  "event_payload": {
    "invoiceId": "INV-20260526-0041",
    "amount": 1250.00,
    "currency": "USD",
    "transactionId": "TXN-88441922",
    "paidAt": "2026-05-26T15:08:44Z"
  },
  "event_name": "payment.completed",
  "received_at": "2026-05-26T15:08:45Z"
}

timed_out port output

{
  "event_wait": {
    "id": 44192,
    "event_name": "payment.completed",
    "correlation_key": "payment.completed:INV-20260526-0041",
    "timed_out_at": "2026-05-27T14:22:00Z"
  }
}

Expression Reference

Node Policies & GuardRails

Examples

Example 1 — Payment Confirmation Gate

An order workflow creates an invoice and emails it to the customer, then suspends waiting for the payment.completed event correlated on the invoice ID. When payment is confirmed via webhook, the event bus resumes the workflow and shipping is triggered. If payment is not received within 24 hours, an overdue reminder is sent.

WebhookTrigger  [key: "orderPlaced"]
  └─► HttpRequest  [key: "createInvoice"]
        POST /invoices  body: { orderId: {{ $json.orderId }}, amount: {{ $json.total }} }
        └─► EmailSmtp  [key: "sendInvoice"]
              To: {{ $json.customerEmail }}
              Subject: "Invoice {{ $output.createInvoice.invoiceId }} — Payment due"
              └─► EventWait  [key: "waitPayment"]
                    event_name: "payment.completed"
                    correlation_id: "{{ $output.createInvoice.invoiceId }}"
                    correlation_field: "invoiceId"
                    timeout_seconds: 86400        // 24-hour payment window
                    event_source: "webhook"
                    ├─► waiting  ──► Slack  (log: "Payment pending — invoice {{ $output.createInvoice.invoiceId }}, wait_id: {{ $output.waitPayment.event_wait.id }}")
                    ├─► success  ──► HttpRequest  (POST /orders/{{ $json.orderId }}/ship
                    │                              body: { transactionId: {{ $output.waitPayment.event_payload.transactionId }} })
                    └─► timed_out ──► EmailSmtp  (To: {{ $json.customerEmail }} — payment overdue notice)

Example 2 — Async External Job with Callback

A workflow triggers a long-running PDF report generation job on an external service, then suspends. When the service completes the job, it publishes a job.finished event via the internal message bus. The workflow resumes, downloads the report URL from the event payload, and emails it to the requester. A 1-hour timeout catches jobs that hang.

FormTrigger  [key: "reportRequested"]
  └─► HttpRequest  [key: "triggerJob"]
        POST /reports/generate  body: { type: {{ $json.reportType }}, userId: {{ $json.userId }} }
        └─► EventWait  [key: "waitJobComplete"]
              event_name: "job.finished"
              correlation_id: "{{ $output.triggerJob.jobId }}"
              correlation_field: "jobId"
              timeout_seconds: 3600
              event_source: "internal"
              ├─► waiting  ──► HttpRequest  (PATCH /jobs/{{ $output.triggerJob.jobId }}  body: { status: "awaiting_callback" })
              ├─► success  ──► EmailSmtp
              │                 To: {{ $json.userEmail }}
              │                 Subject: "Your report is ready"
              │                 Body: "Download: {{ $output.waitJobComplete.event_payload.reportUrl }}"
              └─► timed_out ──► EmailSmtp  (To: {{ $json.userEmail }} — report generation timed out, please retry)

Example 3 — Cross-Workflow Approval Signal

An expense submission workflow creates an approval request, emails the approver, then suspends waiting for an approval.decision event. The approver acts via the HR portal, which calls an internal API endpoint that publishes the event with the decision and reason. The waiting workflow resumes and branches on the decision outcome. A 7-day timeout escalates stale approvals.

WebhookTrigger  [key: "expenseSubmitted"]
  └─► MongoDB  [key: "createApproval"]
        (insert: { expenseId: {{ $json.expenseId }}, submittedBy: {{ $json.userId }}, amount: {{ $json.amount }} })
        └─► EmailSmtp  [key: "notifyApprover"]
              To: {{ $json.approverEmail }}
              Subject: "Action required: Expense {{ $json.expenseId }} needs your approval"
              Body: "Approve at {{ $var.portal_url }}/approvals/{{ $output.createApproval.insertedId }}"
              └─► EventWait  [key: "waitDecision"]
                    event_name: "approval.decision"
                    correlation_id: "{{ $output.createApproval.insertedId }}"
                    correlation_field: "approvalRequestId"
                    timeout_seconds: 604800       // 7-day approval window
                    event_source: "internal"
                    ├─► waiting  ──► Slack  (log: "Approval pending, expense: {{ $json.expenseId }}, wait_id: {{ $output.waitDecision.event_wait.id }}")
                    ├─► success  ──► IfCondition
                    │                 Condition: {{ $output.waitDecision.event_payload.decision == "approved" }}
                    │                 ├─► true  ──► HttpRequest  (POST /finance/disburse  body: { expenseId: {{ $json.expenseId }} })
                    │                 └─► false ──► EmailSmtp  (To: submitter — rejected: {{ $output.waitDecision.event_payload.reason }})
                    └─► timed_out ──► EmailSmtp  (To: {{ $json.approverEmail }} — approval request expired after 7 days)