Webhook Trigger in Kestra – Start Flows via HTTP

Trigger flows automatically in response to web-based events.

Webhook trigger – start flows via http

A Webhook trigger generates a unique URL that lets external applications (such as GitHub, Amazon EventBridge, or any system that can send HTTP requests) automatically start new executions in Kestra.

Each webhook URL requires a secret key to secure it. This prevents unauthorized access and ensures only trusted systems can trigger your flow.

type: "io.kestra.plugin.core.trigger.Webhook"

A Webhook trigger enables triggering a flow from a webhook URL. When you create the trigger, you must provide a key. This key is embedded in the webhook URL: /api/v1/main/executions/webhook/{namespace}/{flowId}/{key}.

For security, use a randomly generated string rather than something easy to guess. Kestra accepts GET, POST, and PUT requests on the webhook URL. Both the request body and headers are automatically available as variables inside your flow.

Example

id: trigger
namespace: company.team

tasks:
  - id: hello
    type: io.kestra.plugin.core.log.Log
    message: "Hello World! 🚀"

triggers:
  - id: webhook
    type: io.kestra.plugin.core.trigger.Webhook
    key: 4wjtkzwVGBM9yKnjm3yv8r

After creating the trigger, include the key in the webhook URL to start the flow. For example:

https://{kestra_domain}/api/v1/main/executions/webhook/{namespace}/{flowId}/4wjtkzwVGBM9yKnjm3yv8r

Make sure to replace kestra_domain, namespace, and flowId.

You can also copy the formed Webhook URL from the Triggers tab.

Webhook trigger testing

If your flow uses trigger variables (such as {{ trigger.body }}), you can test it directly from the execution modal. Kestra generates a ready-to-use cURL command that lets you trigger the flow with a custom JSON payload.

See the Webhook trigger plugin documentation for a full list of properties and outputs.

Return flow outputs in the webhook response

To send task outputs back to the caller in the HTTP response, configure the Webhook trigger to wait for the execution and return outputs. The flow must expose at least one outputs entry.

id: webhook_return_outputs
namespace: company.team

tasks:
  - id: make_payload
    type: io.kestra.plugin.core.debug.Return
    format: "Hello {{ trigger.parameters.name[0] ?? 'world' }}!"

outputs:
  - id: greeting
    type: STRING
    value: "{{ outputs.make_payload.value }}"

triggers:
  - id: webhook
    type: io.kestra.plugin.core.trigger.Webhook
    key: 4wjtkzwVGBM9yKnjm3yv8r
    wait: true
    returnOutputs: true
    # optional: responseContentType: "text/plain"

• Call the webhook URL with a query parameter (for example ?name=Alice). The execution runs synchronously because wait: true is set.
• The HTTP response body contains the flow outputs (JSON by default). With the example above, the response includes "greeting": "Hello Alice!".
• Set responseContentType: "text/plain" when you want the response body to be plain text (ensure the flow returns a single string output, such as from the Return task).