How to integrate Unify with Retool Workflows
To integrate Unify with Retool Workflows, POST JSON to a workflow’s webhook endpoint with its X-Workflow-Api-Key header. Retool exposes the incoming data through startTrigger.data so blocks can use it. Publish the intended version and check the action result before calling the handoff complete.[1][3]
- Connection
- Via webhook
- Automation
- Tool
- Retool Workflows
- Retool webhook trigger
- Data flow
- Unify → Retool Workflows
- JSON payload
At a glance
- Choose the resource operation and the person responsible for its result
- Map live startTrigger data to explicit action fields
- Publish and test the intended workflow environment
When this workflow makes sense
Start with the decision your team needs to make, then choose the connection that supports it.
An internal operations handoff is useful when a selected prospect needs a controlled action in a system your team already uses. Decide what that action changes and who investigates a failure. The workflow should turn the record into owned work, with resource permissions and publication treated as part of the implementation.
A good fit when
Teams using Retool to coordinate internal resource operations and able to maintain the receiving workflow.
Reconsider the plan when
If no one owns the connected resource or the action’s repeat behavior, settle those decisions before adding live traffic.
Design the handoff
Use this framework to agree on the input, the next action, and who owns the result.
Suggested workflow design, based on the documented capabilities below.
| Stage | Decision to make |
|---|---|
| Action | Choose the resource operation and the person responsible for its result |
| Mapping | Map live startTrigger data to explicit action fields |
| Version | Publish and test the intended workflow environment |
| Recovery | Trace failures to the resource operation before replaying a request |
Explore the scenarios
Choose the situation that fits your team and work through the proposed plan.
Open a scenario to explore its plan. Checklists track your selections in this page only.
Create an operations task
Selected prospects need an action in an internal resource.
Agree what a useful task contains before adding blocks.
- Choose the resource and required task fields
- Map a fictional incoming record
- Inspect the task with its intended owner
Check a workflow version change
The team changes mapping or resource behavior after initial setup.
Test the published entry point as well as the editor.
- Save and publish the intended version
- Send a controlled record through the webhook
- Compare the resource result with the expected mapping
Illustrative workflow, not a preconfigured automation. Complete these checks in your own account.
Define success before launch
Inspect the data and the intended outcome separately. Connection status is only the first check.
Expected, not tested
The published workflow receives the fictional prospect and completes the intended resource action with the expected fields.
Inspect the triggered run and its resource result. Test editor inputs and a successful HTTP acknowledgement are separate from successful execution of the published workflow.
Documentation-based reference. This workflow has not been tested end to end. Use a record or event you control before enabling live activity.
Questions answered
Common decisions when connecting Unify and Retool Workflows.
How do I connect Unify to Retool Workflows?
Send a JSON POST from a Unify Play to the workflow’s copied endpoint with its workflow API key.[3]
Where do I read prospect fields in Retool?
Use startTrigger.data for the incoming JSON object. A flat prospect_email property is available as startTrigger.data.prospect_email.[3]
Do test JSON parameters replace a real webhook payload?
No. Retool uses test parameters for manual runs. Webhook-triggered runs use the real data sent by Unify.[3]
Why should I publish the workflow?
Publishing makes the intended workflow version available for automatic execution. Confirm the version and environment before testing the live endpoint.[4]
Will a Response block enrich the Unify Play?
No. Unify does not pass webhook response bodies to later Play steps, even if Retool returns useful data in its Response block.[2]
Limits & decisions
Check these boundaries before designing a live workflow around the connection.
- The workflow must have the appropriate resource access and published configuration
- API-key rotation requires updating the sender
- A resource action may have its own failure and duplicate behavior
- No live Retool run or resource mutation has been tested
What the connection supports
Understand the connection, the data involved, and the behavior that matters for a Unify + Retool Workflows workflow.
POST / JSON
| Decision | What to know |
|---|---|
| Intake | JSON POST to the configured webhook endpoint[3] |
| Authentication | X-Workflow-Api-Key is the recommended request header[3] |
| Mapping | Live JSON is available in startTrigger.data[3] |
| Publication | Published workflow versions control automatic execution[4] |
| Diagnosis | Workflow observability exposes run behavior and failures[5] |
Technical setup reference
References and requirements for the Retool Workflows connection.
Connection requirements and setup checklist
Before connecting
- A Unify Play with a Webhook action
- A Retool workflow with a configured webhook trigger
- Resource connections permitted to perform the chosen action
- A published version and an operator responsible for the result
Configure the entry point
Open startTrigger or the Triggers panel and configure a webhook trigger. Copy its endpoint and workflow-specific key. Keep API-key authentication enabled.[3]
Publish the intended logic
Connect the blocks for the chosen action and publish the workflow version you want automatic runs to use. Recheck the target environment and resource settings when publishing.[4]
Request configuration
- Method
POST- URL pattern
https://api.retool.com/v1/workflows/YOUR_WORKFLOW_ID/startTrigger- Headers
Content-Type: application/jsonX-Workflow-Api-Key: YOUR_WORKFLOW_API_KEY- Authentication
- In Unify, use API Key (Header) with X-Workflow-Api-Key and the workflow’s key. Keep the trigger private. Copy the endpoint from your deployment instead of assuming the Cloud example applies to a self-hosted instance.
Choose JSON as the body format. Unify sets Content-Type automatically. The receiver must respond within Unify’s 8-second timeout; request responses are not passed to later Play steps.[2]
Replace URL placeholders with the actual receiver URL from your account or deployed application. These example URLs are not working endpoints.
Example handoff payload
Start with a fictional prospect. Validate the resolved values before using a real record.
Inspect the sample payload and field mapping
{
"event": "prospect_handoff",
"prospect_name": "Alex Morgan",
"prospect_email": "alex@example.com",
"company_name": "Example Company",
"company_domain": "example.com"
}Fictional data. Replace sample values before using a real Play.
The keys are an example handoff format, not required Unify field names. Use the field mapping to distinguish record data from fixed settings. Select available fields in your Play and inspect Expand preview; do not replace configuration values with prospect data.[2]
| Payload field | Value to send |
|---|---|
event | A fixed label you choose for this workflow |
prospect_name | Use {{ person.first_name }} and {{ person.last_name }} for the prospect name |
prospect_email | Use {{ person.email }}; decide how to handle missing values |
company_name | Use {{ company.name }} |
company_domain | Use {{ company.domain }} |
For this flat payload, downstream blocks read properties such as startTrigger.data.prospect_email. Retool test inputs are for manual runs; an actual webhook run uses the incoming request data.
Troubleshooting
Start with the stage where the expected data or action stops appearing.
The request returns an authentication error
Compare the workflow-specific key and X-Workflow-Api-Key header. Rotating a key immediately invalidates the previous one, so update the Unify configuration too.[3]
The editor works but automatic runs differ
Check the published workflow version and environment. Confirm that live runs use the actual incoming JSON rather than the manual test values.[3][4]
A downstream action fails
Inspect the configured resource, its credentials, and block input. Use workflow observability to locate the failing operation and check the destination before retrying.[5]
Sources & review
Official documentation reviewed on September 15, 2026.
Technical claims link to primary documentation from Unify and the destination tool. Scenarios, field choices, and recovery plans are editorial implementation examples. Documentation review is separate from execution testing.
Documentation reviewed; end-to-end execution not tested. No named technical reviewer has signed off on these articles yet.
Content updated: . Report a correction to Unify with the tool name, source URL, and behavior you observed.
Keep exploring
