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​

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.

You can optionally provide example JSON values, such as an existing payload, to build and test your workflow in the Workflow IDE. Update Test JSON Parameters to include relevant JSON. Test parameters are also included when copying 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.