Await External Event

	Component	Type	Description
	Await External Event	⏸️ pause	pause workflow execution and wait for an external event (webhook or API polling) that matches a condition before continuing

The Await External Event component allows you to pause a running workflow and wait for an external event before continuing. Unlike trigger components that start new workflows, this component is used mid-workflow to wait for external systems to signal completion, status changes, or other events.

When to Use

This component is ideal for:

Asynchronous Processing: Wait for a long-running external process to complete before continuing
Event-Driven Workflows: Pause until an external system sends a webhook notification
Polling for Status: Periodically check an external API until a specific condition is met
Human-in-the-Loop Integration: Wait for external approval systems to respond

Event Source Modes

The component supports two modes for receiving external events:

Webhook Mode

In webhook mode, the component provides a URL that external systems can POST data to. The component supports two webhook modes:

Static Webhook (Recommended for most use cases)

A static webhook URL is generated when you save the workflow and remains the same across all workflow runs. This allows you to pre-configure the webhook URL in external systems.

Static Webhook URL Format:

https://api.workflow86.com/await_external_event/webhook/{componentId}/{token}

Benefits:

URL is immediately available after saving the workflow
Can be pre-configured in external systems (CRM, payment gateways, etc.)
No need for the workflow to "pass" the URL to external systems

Correlation Field (for concurrent workflows): If multiple workflow sessions may be waiting simultaneously on the same component, you can configure a correlation field. The component will extract this field's value from the webhook payload to match it to the correct waiting session (e.g., order_id, job_id).

Dynamic Webhook

A unique webhook URL is generated for each workflow session when it reaches this component. Use this when you need the workflow to explicitly pass the callback URL to an external system.

Dynamic Webhook URL Format:

https://api.workflow86.com/await_external_event/webhook/{sessionToken}

When to use:

When you want complete isolation between workflow sessions
When the external system expects the callback URL to be provided as part of the request

When the workflow reaches this component:

A unique webhook token is generated for this specific workflow session
The workflow pauses (enters WAITING state)
The webhook URL is available as a placeholder for subsequent components to use
External systems can POST data to the webhook URL
When data is received and the condition is met, the workflow resumes

API Polling Mode

In polling mode, the component periodically polls an external API endpoint and checks if the response matches a configured condition:

The workflow pauses (enters WAITING state)
The component polls the configured API at regular intervals
Each response is evaluated against the condition
When a response matches the condition, the workflow resumes

Configuration

Event Source

Select how the component should receive external events:

Webhook - External systems POST data to a unique endpoint
API Polling - Component polls an external API at intervals

Webhook Configuration

Webhook Mode Selection

Choose between Static URL and Dynamic URL based on your use case:

Mode	URL Generation	Best For
Static URL	Generated when workflow is saved	Pre-configuring external integrations, payment webhooks, CRM callbacks
Dynamic URL	Generated per workflow session	When workflow explicitly passes callback URL to external systems

Static Webhook Configuration

Save the workflow to generate your static webhook URL
Copy the URL from the component configuration panel
Configure this URL in your external system
(Optional) Set a Correlation Field if multiple workflows may wait simultaneously

Static Webhook URL

The static webhook URL is stable - you only need to configure it once in your external system. It will work for all future workflow runs.

Dynamic Webhook Configuration

The dynamic webhook URL is available as a placeholder when the workflow reaches this component. Use it in subsequent components (like API Request or Email) to send the callback URL to external systems.

Dynamic Webhook URL Availability

With dynamic mode, the webhook URL is only available when a workflow session is actively waiting at this component. Each workflow session gets a unique token.

API Polling Configuration

When using polling mode, configure the following:

API Endpoint URL

Enter the URL of the API endpoint to poll. You can use placeholders for dynamic values, including:

Secrets: Type $ to insert secrets stored in your credential store (e.g., ${API_KEY.SECRET})
Placeholders: Insert values from previous components in the workflow

HTTP Method

Select the HTTP method to use for polling:

GET - Retrieve data from the endpoint (default)
POST - Send data to the endpoint
PUT - Update data at the endpoint
DELETE - Delete data at the endpoint

Headers

Add custom HTTP headers to include with each poll request. Click the + button to add key-value pairs. Header values support placeholders and secrets.

Query Parameters

Add URL query parameters to include with each poll request. Click the + button to add key-value pairs.

Request Body

For POST and PUT requests, enter the request body content. You can include placeholders and secrets.

Polling Interval

Configure how often the API should be polled while waiting:

Interval Value - The number of time units between polls (minimum: 1)
Interval Type - Minutes, Hours, or Days

Response Format

Select the expected response format:

JSON - Parse response as JSON (default)
XML - Parse response as XML
Plain Text - Treat response as plain text

Resume Condition

Configure the condition that must be met for the workflow to resume. The condition evaluates the incoming data (webhook payload or API response) and resumes when matched.

Condition Type

Select the type of condition to use:

Type	Description	Use Case
Field Path	Simple dot notation (e.g., `data.status`)	Most common - accessing specific fields in JSON
JSONPath	JSONPath expression (e.g., `$.data.items[*].status`)	Complex JSON navigation, arrays, filtering
Regex	Match a regex pattern against the entire response	Pattern matching across the whole response
Text Search	Search for text with AND/OR logic	Finding specific text combinations anywhere in response

Field Path / JSONPath / Regex Expression

Enter the expression based on your selected condition type:

Field Path examples:

status - Top-level field
data.state - Nested field
result.items[0].completed - Array access with nested field

JSONPath examples:

$.status - Top-level field
$.data.items[*].status - All status fields in items array
$.data.items[?(@.active==true)].id - IDs of active items

Regex examples:

"status":\s*"completed" - Match status field with completed value
error|failed|timeout - Match any error-related text

Operator

Select the comparison operator:

Operator	Description
Equals	Field value exactly matches expected value
Not equals	Field value does not match expected value
Contains	Field value contains expected value as substring
Does not contain	Field value does not contain expected value
Starts with	Field value starts with expected value
Ends with	Field value ends with expected value
Greater than	Field value is numerically greater than expected
Less than	Field value is numerically less than expected
Greater than or equals	Field value is greater than or equal to expected
Less than or equals	Field value is less than or equal to expected
Matches regex	Field value matches a regular expression pattern
In list	Field value matches one of the comma-separated values
Not in list	Field value does not match any of the comma-separated values
Is empty	Field value is null, undefined, or empty string
Is not empty	Field value exists and is not empty
Exists	Field exists in the data (regardless of value)
Does not exist	Field does not exist in the data

Expected Value

Enter the value to compare against (not required for operators like "is empty", "exists", etc.).

For In list and Not in list operators, enter comma-separated values: completed, done, finished

Example Conditions:

Scenario	Type	Expression	Operator	Expected Value
Wait for status "completed"	Field Path	`status`	Equals	`completed`
Wait for progress >= 100	Field Path	`progress`	Greater than or equals	`100`
Wait for any success status	Field Path	`status`	In list	`completed, done, success`
Wait for error field to be empty	Field Path	`error`	Is empty	(none)
Wait for completed pattern in response	Regex	`"status":\s*"completed"`	Matches regex	(pattern in expression)
Wait for any item to be ready	JSONPath	`$.items[*].ready`	Equals	`true`

Text Search Conditions

When using Text Search condition type, you can define multiple search rules with AND/OR logic:

Click Add Rule to add a search condition
For each rule, configure:
- Contains / Does NOT contain - Whether the text should or shouldn't be present
- Case sensitive - Enable for case-sensitive matching
- Search text - The text to search for (supports placeholders)
Use the connector button between rules to toggle between AND (all rules must match) and OR (any rule in the group can match)

Text Search Examples:

Scenario	Rules
Wait for "success" anywhere	Contains: `success`
Wait for "completed" but not "error"	Contains: `completed` AND Does NOT contain: `error`
Wait for "approved" or "accepted"	Contains: `approved` OR Contains: `accepted`

Empty Condition

If you leave the condition empty (no expression specified), the workflow will resume on any incoming event.

Timeout Configuration (Optional)

Enable timeout to set a maximum wait time. If the condition is not met before the timeout:

Timeout Duration

Set the maximum time to wait:

Value - Number of time units
Type - Minutes, Hours, or Days

Timeout Behavior

Choose what happens when the timeout is reached:

Error - Fail the workflow with a timeout error
Continue - Complete successfully with a timeout flag (the output will indicate a timeout occurred)

Output Placeholder

Configure the placeholder key where the event data will be stored. When the workflow resumes, the data from the event that triggered the resume (webhook payload or API response) is stored in this placeholder as JSON.

Session Status

The component UI displays information about active waiting sessions:

Active sessions: How many workflow sessions are currently waiting at this component
Session details: Session ID, event source mode, and waiting status
Webhook URL: For active webhook mode sessions, the webhook URL is displayed with a copy button

Use the Refresh button to update the session information.

How It Works

Execution Flow

Workflow starts
    ↓
Previous components execute
    ↓
Await External Event reached
    ↓
Session enters WAITING state
    ↓
[Webhook Mode]              [Polling Mode]
Wait for POST ←────────or────────→ Poll API at intervals
    ↓                              ↓
Evaluate condition ←──────────────→ Evaluate condition
    ↓                              ↓
    ←───────── Condition met? ─────────→
         No (wait for next)    Yes (resume)
                                   ↓
                            Session enters SUCCESS state
                                   ↓
                            Subsequent components execute

Timeout Flow

If timeout is configured and reached before the condition is met:

Timeout reached
    ↓
[Error behavior]          [Continue behavior]
    ↓                           ↓
Session FAIL              Session SUCCESS
Workflow stops            Output includes timeout=true
                          Workflow continues

Best Practices

Use meaningful conditions - Design conditions that clearly indicate when it's appropriate to resume. Avoid overly broad conditions that might match unintended events.
Set appropriate timeouts - Always consider adding a timeout for production workflows. This prevents workflows from waiting indefinitely if the expected event never arrives.
Secure webhook endpoints - While webhook tokens are random and unique per session, consider the security implications of your webhook endpoints and what data is transmitted.
Monitor active sessions - Use the session status in the component UI to monitor waiting sessions. Many long-waiting sessions might indicate a configuration issue.
Handle timeouts gracefully - If using "Continue" timeout behavior, design your subsequent workflow logic to check for and handle the timeout condition appropriately.
Use polling intervals wisely - When using polling mode, balance responsiveness with API load. More frequent polling means faster detection but more API calls.
Store API secrets securely - Use the credential store for API keys and tokens. Never hardcode sensitive values in the component configuration.
Choose the right condition type - Use Field Path for simple JSON fields, JSONPath for complex nested data or arrays, Regex for pattern matching, and Text Search when you need to find text anywhere in the response with flexible AND/OR logic.
Use In list for multiple valid values - Instead of creating complex OR conditions, use the "In list" operator when waiting for any of several acceptable values (e.g., completed, done, finished).
Test regex patterns - When using regex conditions, test your patterns against sample data before deploying. Remember to escape special regex characters like ., *, ?, etc.

Troubleshooting

Issue	Possible Cause	Solution
Workflow not resuming	Condition not matching	Check the condition configuration; verify the field path/expression is correct
Webhook not received	Wrong URL or token	Verify the webhook URL is correct and the token hasn't expired
Polling not working	API returning errors	Check poll history for error messages; verify credentials
Session stuck waiting	No events received	Check if external system is configured correctly; verify timeout settings
Wrong data in output	Response format mismatch	Change the response format setting (JSON/XML/Text)
Timeout not triggering	Timeout not enabled	Enable timeout in the configuration
JSONPath not matching	Invalid JSONPath syntax	Verify JSONPath expression; ensure it starts with `$`
Regex not matching	Pattern syntax error	Test your regex pattern; escape special characters properly
Text search not finding text	Case sensitivity	Try disabling case-sensitive matching; check for extra whitespace
In list operator not matching	Whitespace in values	Ensure no extra spaces around comma-separated values

Example Use Cases

Wait for External Approval

A workflow that sends a request for approval to an external system and waits for the response:

Previous component sends approval request to external system (with webhook callback URL)
Await External Event (webhook mode) waits for approval response
Condition: approved equals true
Next component processes based on approval status

Poll for Job Completion

A workflow that starts a long-running job and polls for completion:

Previous component starts a job via API, receives job ID
Await External Event (polling mode) polls job status endpoint
Condition: status equals completed
Timeout: 1 hour with error behavior
Next component retrieves job results

Wait for Payment Confirmation

A workflow that processes orders and waits for payment:

Previous component creates order and sends payment request
Await External Event (webhook mode) waits for payment webhook
Condition: payment.status equals successful
Timeout: 24 hours with continue behavior
Next component handles successful payment or timeout

Await External Event

When to Use​

Event Source Modes​

Webhook Mode​

Static Webhook (Recommended for most use cases)​

Dynamic Webhook​

API Polling Mode​

Configuration​

Event Source​

Webhook Configuration​

Webhook Mode Selection​

Static Webhook Configuration​

Dynamic Webhook Configuration​

API Polling Configuration​

API Endpoint URL​

HTTP Method​

Headers​

Query Parameters​

Request Body​

Polling Interval​

Response Format​

Resume Condition​

Condition Type​

Field Path / JSONPath / Regex Expression​

Operator​

Expected Value​

Text Search Conditions​

Timeout Configuration (Optional)​

Timeout Duration​

Timeout Behavior​

Output Placeholder​

Session Status​

How It Works​

Execution Flow​

Timeout Flow​

Best Practices​

Troubleshooting​

Example Use Cases​

Wait for External Approval​

Poll for Job Completion​

Wait for Payment Confirmation​