Skip to main content
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

  1. You create a subscription (POST /event-subscriptions) binding an event_type string to a Definition you own.
  2. Somewhere in a flow, a task uses getdialed__utils__emit_event to emit an event with that event_type.
  3. Every enabled subscription with a matching event_type fires its bound Definition, passing the event payload as the new job’s input_data.
Cycle protection. The causation chain is threaded through every event-triggered job. 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/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/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/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 never fires until you flip it on — handy while you build and test the Definition it points at.

​
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}
  }
}
ParameterTypeRequiredDescription
event_typestringyesExact event name subscriptions match on
payloadobjectnoEvent 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 (cursor-paginated, newest first), or delete one when it is no longer needed. Events emitted after deletion no longer fire the bound Definition; already-fired jobs are unaffected. 
# List
curl "https://api.getdialed.ai/flows/event-subscriptions?limit=20" \
  -H "X-API-Key: $API_KEY"

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

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

// Delete
await fetch(
  "https://api.getdialed.ai/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/flows/event-subscriptions",
    headers={"X-API-Key": os.environ["API_KEY"]},
    params={"limit": 20},
)
page = res.json()

# Delete
httpx.delete(
    "https://api.getdialed.ai/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.