Subscribe to events

Event subscriptions auto-trigger Definitions from internal business events. A flow author emits an event with the getdialed__utils__emit_event catalog action; every enabled subscription whose event_type exactly matches fires its bound Definition with the event payload as input_data (source: "event"). Matching is exact-name and scoped to your org — no wildcards, no prefixes.

How event subscriptions work

You create a subscription (POST /flows/event-subscriptions) binding an event_type string to a Definition you own.
Somewhere in a flow, a task uses getdialed__utils__emit_event to emit an event with that event_type.
Every enabled subscription with a matching event_type fires its bound Definition, passing the event payload as the new batch’s input_data.

Cycle protection. The causation chain is threaded through every event-triggered batch. If A emits an event that triggers B, which emits one that triggers C, the chain depth is checked before each dispatch — depth > 5 is rejected (CycleDetectedError), cutting off runaway trigger loops at a bounded depth.

Step 1 — Create the subscription

Bind an event name to a Definition you own. The X-API-Key header is admin-equivalent; a Clerk JWT needs the admin role. A missing or cross-tenant definition_id returns 404 (never 403).

curl -X POST https://api.getdialed.ai/v1/flows/event-subscriptions \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "list.refreshed",
    "definition_id": "def_a1b2c3d4"
  }'

const res = await fetch(
  "https://api.getdialed.ai/v1/flows/event-subscriptions",
  {
    method: "POST",
    headers: {
      "X-API-Key": process.env.API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      event_type: "list.refreshed",
      definition_id: "def_a1b2c3d4",
    }),
  },
);
const subscription = await res.json();

import os
import httpx

res = httpx.post(
    "https://api.getdialed.ai/v1/flows/event-subscriptions",
    headers={"X-API-Key": os.environ["API_KEY"]},
    json={
        "event_type": "list.refreshed",
        "definition_id": "def_a1b2c3d4",
    },
)
subscription = res.json()

{
  "id": "evsub_9f8e7d6c5b4a",
  "org_id": "org_12345678",
  "event_type": "list.refreshed",
  "definition_id": "def_a1b2c3d4",
  "enabled": true,
  "created_at": "2026-07-07T20:00:00Z",
  "updated_at": "2026-07-07T20:00:00Z"
}

Set "enabled": false to register a subscription that stays dormant — it never fires while disabled. There is no update endpoint yet, so a disabled subscription cannot be re-enabled in place: delete it and recreate it with "enabled": true (or just create it enabled once the Definition it points at is ready).

Step 2 — Emit the event from a flow

Subscriptions only fire on deliberately emitted events — system/lifecycle events are not auto-emitted. Add a getdialed__utils__emit_event task to any Definition. The payload you emit becomes the fired Definition’s input_data:

{
  "task_id": "notify",
  "action_id": "getdialed__utils__emit_event",
  "parameters": {
    "event_type": "list.refreshed",
    "payload": {"list_name": "prod", "count": 1200}
  }
}

Parameter	Type	Required	Description
`event_type`	string	yes	Exact event name subscriptions match on
`payload`	object	no	Event body — becomes each fired Definition’s `input_data`. Default `{}`.

When this task runs, the list.refreshed subscription created above fires def_a1b2c3d4 with {"list_name": "prod", "count": 1200} as its input_data. Emission runs as a durable task inside your worker, so transient delivery failures are covered by the standard retry policy.

Manage subscriptions

List your org’s subscriptions with offset pagination (limit/skip), newest first by default, or delete one when it is no longer needed. The response is the standard Page envelope — items, a real total (the filtered count), the echoed limit/skip, and next_cursor (always null on this offset-paginated list); filter with event_type and order with sort_by/order. Events emitted after deletion no longer fire the bound Definition; already-fired batches are unaffected.

# List
curl "https://api.getdialed.ai/v1/flows/event-subscriptions?limit=20&skip=0" \
  -H "X-API-Key: $API_KEY"

# Delete
curl -X DELETE https://api.getdialed.ai/v1/flows/event-subscriptions/evsub_9f8e7d6c5b4a \
  -H "X-API-Key: $API_KEY"

// List
const res = await fetch(
  "https://api.getdialed.ai/v1/flows/event-subscriptions?limit=20&skip=0",
  { headers: { "X-API-Key": process.env.API_KEY } },
);
const { items, total } = await res.json();

// Delete
await fetch(
  "https://api.getdialed.ai/v1/flows/event-subscriptions/evsub_9f8e7d6c5b4a",
  { method: "DELETE", headers: { "X-API-Key": process.env.API_KEY } },
);

import os
import httpx

# List
res = httpx.get(
    "https://api.getdialed.ai/v1/flows/event-subscriptions",
    headers={"X-API-Key": os.environ["API_KEY"]},
    params={"limit": 20, "skip": 0},
)
page = res.json()

# Delete
httpx.delete(
    "https://api.getdialed.ai/v1/flows/event-subscriptions/evsub_9f8e7d6c5b4a",
    headers={"X-API-Key": os.environ["API_KEY"]},
)

Next steps

Event subscriptions

The full object reference, matching rules, and cycle protection.

Catalog

The getdialed__utils__emit_event action and everything else you can call from a flow.

Getting Started

Core Concepts

Building Flows

Triggers & Streaming

How event subscriptions work

Step 1 — Create the subscription

Step 2 — Emit the event from a flow

Manage subscriptions

Next steps

Event subscriptions

Catalog

​How event subscriptions work

​Step 1 — Create the subscription

​Step 2 — Emit the event from a flow

​Manage subscriptions

​Next steps

Event subscriptions

Catalog

How event subscriptions work

Step 1 — Create the subscription

Step 2 — Emit the event from a flow

Manage subscriptions

Next steps