Set up webhook automations

Send events from your tools to a named Flow automation. The webhook name becomes the request’s source; the context object carries the event data.

Before you start

Use an API key and workspace identifier, and identify the project that owns the automation. Use the variables and language setup from the quickstart, with PROJECT_ID set to that project’s ID.

Configure the automation

Requires you to act: In your project, open Agent → Automations → New automation and configure the trigger:

Give the automation a descriptive Name, such as Review test results.
Set Trigger to When a custom webhook is called.
Set Webhook name to test-results-ready.

Use the exact webhook name in API requests, including capitalization. Choose a distinct name for each event type. Avoid built-in source names such as endpoint, github, or schedule. If multiple automations in the project share the same source, one request can start them all. Requires you to act: Define the work and save the automation:

In Agent → Instructions, describe the expected input and the actions to take. For example: “Read the test report URL from context.report_url. Summarize failed tests and identify affected requirements. Return a concise summary without changing project data.”
Select Create.

Webhook runs execute without an interactive approval step. Make the instructions explicit about what the automation should read, change, and return.

Send an event

Send an authenticated POST /ai/trigger request with the webhook name, project ID, and JSON context. Replace the sample report URL with one the automation can access. The event_id below is your correlation value; including it does not make repeated requests idempotent.

set -euo pipefail

jq -n --arg project "$PROJECT_ID" '{
  project_id: $project,
  source: "test-results-ready",
  context: {
    event_id: "test-run-123",
    report_url: "https://example.com/test-results/123"
  },
  wait: false
}' > webhook-event.json

curl --fail-with-body --silent --show-error \
  "$FLOW_API_URL/ai/trigger" \
  -H "X-API-Key: $FLOW_API_KEY" \
  -H "customer: $FLOW_CUSTOMER" \
  -H "Content-Type: application/json" \
  --data-binary @webhook-event.json \
  -o trigger-response.json

jq '.results[] | {agent_id, automation_id, status}' trigger-response.json

import json
import os
import requests

base_url = os.environ["FLOW_API_URL"].rstrip("/")
response = requests.post(
    f"{base_url}/ai/trigger",
    headers={
        "X-API-Key": os.environ["FLOW_API_KEY"],
        "customer": os.environ["FLOW_CUSTOMER"],
    },
    json={
        "project_id": os.environ["PROJECT_ID"],
        "source": "test-results-ready",
        "context": {
            "event_id": "test-run-123",
            "report_url": "https://example.com/test-results/123",
        },
        "wait": False,
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
with open("trigger-response.json", "w") as output:
    json.dump(data, output, indent=2)
for run in data["results"]:
    print({key: run[key] for key in ("agent_id", "automation_id", "status")})

import { writeFile } from "node:fs/promises";

const baseUrl = process.env.FLOW_API_URL.replace(/\/$/, "");
const response = await fetch(`${baseUrl}/ai/trigger`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.FLOW_API_KEY,
    customer: process.env.FLOW_CUSTOMER,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    project_id: process.env.PROJECT_ID,
    source: "test-results-ready",
    context: {
      event_id: "test-run-123",
      report_url: "https://example.com/test-results/123",
    },
    wait: false,
  }),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const data = await response.json();
await writeFile("trigger-response.json", JSON.stringify(data, null, 2));
for (const { agent_id, automation_id, status } of data.results) {
  console.log({ agent_id, automation_id, status });
}

HTTP 202 means the request was accepted, not that the work has finished. Store each agent_id from results and poll for completion. An empty results array means no runs matched; check the saved webhook name and project ID.

Connect your event sender

Your sender must authenticate to Flow and produce the request body above. If an external service cannot set the required headers or transform its event into source and context, use a server-side handler that validates the incoming event and calls Flow with your API key. Keep credentials in the sender’s secret storage. Record the sender’s event ID alongside the returned run IDs so you can trace deliveries and suppress duplicates before triggering Flow. After a network timeout, check for an existing run before resending: the first request can still be executing. For apps already connected through Flow’s Integrations, use the corresponding app trigger. This custom webhook guide covers events you send through the customer API.

Next steps

Trigger and poll automations for run statuses and retry behavior.
Trigger from any source for the complete request schema.
Poll automation runs for the result schema.

Quickstart

Examples

Automations

Flow MCP

Endpoints

Set up webhook automations

Before you start

Configure the automation

Send an event

Connect your event sender

Next steps

​Before you start

​Configure the automation

​Send an event

​Connect your event sender

​Next steps

Before you start

Configure the automation

Send an event

Connect your event sender

Next steps