Skip to main content

Trigger workflows with webhooks

Learn how to automate tasks using webhook events with Retool Workflows.

You can add webhook triggers that run workflows automatically whenever it receives a webhook event, such as a service monitoring alert or when a payment is received. The workflow can reference data in the event's JSON payload in the same way as other block data. If necessary, you can also configure a workflow to respond to webhook events using the Response block, returning data back to the webhook origin.

Add a webhook trigger​

To add a trigger, click the startTrigger block or open the Triggers tab in the left panel.

Send a webhook event​

Do not publicize endpoint URLs

Any request sent to the specified endpoint will trigger the workflow. Do not share or publicize this information.

Copy the endpoint URL and use it as the webhook event destination to trigger webhook events. Webhook events sent to the workflow endpoint must use Content-Type: application/json. A JSON payload is optional.

You can also copy the provided cURL command to send an event as you build and test your workflow.

Example cURL command
curl -X POST --url "https://api.retool.com/v1/workflows/43rewfs-7da9-ddgfet32-fddfr3-43rewf344gre/startTrigger" --data '{"hello":"world"}' -H 'Content-Type: application/json' -H 'X-Workflow-Api-Key: retool_wk_fdsedgf3t4t3grg34354656'

Retrieve event payload​

Workflows can read data from a webhook event's JSON payload (e.g., error message or confirmation number) and make it available to your workflow. You can then use these parameters anywhere in your workflows with the startTrigger object. You can optionally provide example JSON input, such as an existing payload, to build and test your workflow in the workflow IDE. The specified JSON is also included in the curl command.

Retrieve data from the webhook payload.

Rotating API Key​

To rotate the API key, click the Rotate button from the webhook trigger panel. This action generates a new API key and immediately invalidates the previous one. Update any callsites with the new API key to continue triggering the workflow successfully.

Key rotation is immediate and the previous key will no longer work. Depending on your use case, it may take time to update your services and integrations, which can cause downtime. Since each workflow has a unique API key, an alternative approach is to duplicate an existing workflow and update your services or integrations to use it.

  1. Navigate to your organization's list of workflows.
  2. Click ••• and select Duplicate workflow.
  3. Deploy the duplicated workflow.

Update all services and integrations to use the new workflow. Once completed, you can safely delete the old workflow.