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.

Create webhook alias and path parameters

Use the Alias setting to create a custom URL path for your webhook trigger. The resulting webhook URL is formatted as https://{domain}/url/{alias}. For example: https://example.retool.com/url/test-webhook. Enable the Public setting if you want it to be possible to call your webhook URL without the API key.

You can also configure your custom URL path to include dynamic path parameters. This allows you to capture variable data directly from the request path and pass it to the workflow as input. Reference path parameters using startTrigger.pathParams.

For example, you could set Alias to /orders/:id/status. A user would send a request to https://example.retool.com/url/my-custom-alias/orders/12345/status. The path parameter :id is dynamically resolved to 12345, and this value is then passed to the workflow as part of the execution input.

Dynamic path parameters have a few limitations that you must keep in mind:

• Only required, string parameters are supported. No wildcard parameters.
• Paths much be unique. For example, Retool disallows the creation of /orders/:id if /orders/:status already exists.
• Do not use duplicate parameter names, such as /orders/:id/status/:id.
• The first segment of the alias must be static.
• Do not include trailing slashes.

Test headers and parameters

Use the Test Headers, Test Path Parameters and Test JSON Parameters settings in the Trigger block of your workflow to test your trigger without needing to manually call the endpoint.

You can reference the startTrigger.headers, startTrigger.pathParams, and startTrigger.data properties in the rest of your workflow.

Test headers and parameters are used only for manual runs. For actual runs triggered via webhook, real data is used instead.

Configure test headers and parameters.

Send a webhook event

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'

Authenticate webhook events

You can authenticate webhook events by using one of the following in the request:

• The X-Workflow-Api-Key header.
• The workflowApiKey query parameter.

Retool recommends using X-Workflow-Api-Key header unless your intended usage only supports query parameters (e.g., third-party integrations). Be wary when including the secret API key as a query parameter as it can be logged since it is part of the URL.

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. The following example of a Stripe event that occurs when a Setup Intent is created. This event payload includes details about the event, including the Setup Intent's properties.

Stripe event

{
  "id": "evt_1NG8Du2eZvKYlo2CUI79vXWy",
  "object": "event",
  "api_version": "2019-02-19",
  "created": 1686089970,
  "data": {
    "object": {
      "id": "seti_1NG8Du2eZvKYlo2C9XMqbR0x",
      "object": "setup_intent",
      "application": null,
      "automatic_payment_methods": null,
      "cancellation_reason": null,
      "client_secret": "seti_1NG8Du2eZvKYlo2C9XMqbR0x_secret_O2CdhLwGFh2Aej7bCY7qp8jlIuyR8DJ",
      "created": 1686089970,
      "customer": null,
      "description": null,
      "flow_directions": null,
      "last_setup_error": null,
      "latest_attempt": null,
      "livemode": false,
      "mandate": null,
      "metadata": {},
      "next_action": null,
      "on_behalf_of": null,
      "payment_method": "pm_1NG8Du2eZvKYlo2CYzzldNr7",
      "payment_method_options": {
        "acss_debit": {
          "currency": "cad",
          "mandate_options": {
            "interval_description": "First day of every month",
            "payment_schedule": "interval",
            "transaction_type": "personal"
          },
          "verification_method": "automatic"
        }
      },
      "payment_method_types": [
        "acss_debit"
      ],
      "single_use_mandate": null,
      "status": "requires_confirmation",
      "usage": "off_session"
    }
  },
  "livemode": false,
  "pending_webhooks": 0,
  "request": {
    "id": null,
    "idempotency_key": null
  },
  "type": "setup_intent.created"
}

You can then reference event properties anywhere in your workflows with the startTrigger.data object. For the example above, you can reference the Setup Intent ID within the payload using {{ startTrigger.data.data.object.id }}, which is seti_1NG8Du2eZvKYlo2C9XMqbR0x.

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.

Best practices for key rotation

To minimize disruption during webhook API key rotation, especially in enterprise and multi-instance environments, follow these best practices:

• Plan for manual rotation: A developer or admin must click Rotate in production currently. In multi-instance deployment, developers may not have production access. Teams should explicitly define who is responsible for rotating keys.
• Avoid breaking dependencies: Duplicating or moving workflows can break app or workflow triggers, UUID-based references, and git history.
• Keep external webhooks thin: Use webhook workflows only as entry points and forward requests to internal, triggered workflows.
• Adopt clear naming conventions: Distinguish between external and internal workflows (e.g., name the workflow External Webhook: My Key Action), and use aliases to keep external URLs stable.
• Validate end-to-end: After rotation, confirm all triggers and downstream workflows still function correctly.