Why it matters
Some processes should not continue immediately. A reminder may need to wait for several hours, while an external service may need time to finish a task and return a result. Whippy provides a simple Wait Step for time-based delays and three Wait For modes for asynchronous external work.
Key Concepts
Wait Step: Pauses execution for a configured duration or until its configured time condition is reached.
Wait For: Pauses while Whippy waits for an external result.
Webhook Mode: Resumes when an external system calls the workflow’s callback URL.
Polling Mode: Repeatedly checks an external endpoint until a validation condition passes.
Webhook and Polling Mode: Accepts a webhook callback while also polling as a fallback.
Setup Step: Registers or starts the external job before waiting.
Validation Step: Checks whether the external result is ready or acceptable.
Cleanup Step: Removes an external subscription or performs cleanup after completion.
Timeout: The limit after which the workflow stops waiting.
Choose Wait or Wait For
Use Wait Step when the only requirement is for time to pass.
Use Wait For when the workflow depends on an external event or asynchronous job.
Examples:
Wait 30 minutes before sending a follow-up: Wait Step
Wait for a document-processing service to call back: Wait For Webhook
Check an export job until it is complete: Wait For Polling
Prefer a callback but poll in case it is missed: Wait For Webhook and Polling
Add a Wait Step
Step-by-Step: Pause for a Duration
Add Wait Step where the delay should begin.
Configure the duration or available time condition.
Confirm the intended units and timing.
Save the step.
Add the next step after the wait.
Test the surrounding steps.
Publish the workflow.
Review a live run to confirm the delay behaves as intended.
Remember that long waits keep a workflow run in progress. Do not use a Wait Step merely to schedule recurring work; use a Schedule trigger instead.
Wait For Webhook
Webhook mode generates a callback URL. The external service calls that URL when its work is complete.
A typical pattern is:
An HTTP setup step starts the external job and supplies the callback URL.
The workflow pauses.
The external service calls the callback URL.
Whippy stores the callback payload as the Wait For output.
The workflow continues.
Step-by-Step: Configure Webhook Mode
Add Wait For Webhook.
Add the required setup HTTP step inside the Wait For section.
Configure the external request.
Include the callback URL where the external service expects it.
Configure the timeout.
Add the next step after the Wait For section.
Test with a service that can send a safe callback.
Publish and review the run details.
The callback URL identifies a specific waiting execution. Treat it as sensitive and send it only to the intended service.
Wait For Polling
Polling mode calls an endpoint repeatedly and evaluates the returned data.
A typical pattern is:
An earlier action starts an asynchronous job.
The workflow enters Wait For Polling.
A validation action checks the job status.
A condition determines whether the expected result is ready.
Whippy checks again until the condition passes or the wait times out.
Step-by-Step: Configure Polling Mode
Add Wait For Polling after the step that starts the external job.
Add the available validation Code Step or Conditional Path.
Configure the status check using the external job identifier.
Define the success condition.
Configure the polling interval and timeout where available.
Add the steps that should run after the wait succeeds.
Test with a short-running external job.
Review how many checks were made and what output continued downstream.
Use a reasonable polling interval. Checking too often can consume API limits without making the process materially faster.
Wait For Webhook and Polling
Combined mode is useful when a callback is preferred but you also want Whippy to check for completion if the callback is delayed or missed.
The flow can include:
Setup HTTP steps to register the callback or start the job
Validation Code Steps or Conditional Paths
Cleanup HTTP steps to remove a temporary subscription
Steps outside the Wait For section that run after completion
Step-by-Step: Configure Combined Mode
Add Wait For Webhook and Polling.
Configure the setup HTTP action.
Configure the validation steps and success conditions.
Add cleanup HTTP actions when the external service requires them.
Set an appropriate timeout and polling interval.
Add the next workflow step outside the Wait For section.
Test the callback path.
Test the polling fallback.
Confirm cleanup occurs as intended.
Place Steps Correctly
Wait For is a structured container. The step picker changes according to whether you are adding setup, validation, cleanup, or post-wait behavior.
Put registration and job-start requests in setup.
Put readiness checks in validation.
Put subscription removal in cleanup.
Put business actions that should happen after success outside the Wait For section.
Tips and Best Practices
Use the simplest wait type that meets the requirement.
Prefer webhooks when the external service reliably supports callbacks.
Use polling when the service only exposes a status endpoint.
Use combined mode for important jobs where a missed callback needs a fallback.
Set a finite timeout.
Avoid aggressive polling intervals.
Preserve external job IDs in step output so status checks can reference them.
Test timeout and failure behavior, not only the successful path.
Add an error path or notification when a timeout requires human attention.
Troubleshooting
Issue | Possible Cause | Fix |
The workflow remains in progress | The delay has not elapsed or the external result has not arrived | Open Run Details and inspect the Wait or Wait For execution |
A webhook never resumes the workflow | The external service used the wrong callback URL or did not send the request | Inspect its delivery logs and copy the callback URL again |
Polling never completes | The validation condition checks the wrong field or expected value | Review the status response and update the condition |
The external API rate limit is reached | The polling interval is too frequent | Increase the interval and review the provider’s API limits |
A step is unavailable inside Wait For | Only certain step types are valid in that phase | Use an available setup, validation, or cleanup step, or move the action outside |
Work continues after the wrong result | The success condition is too broad | Test the validation logic with incomplete, failed, and completed responses |