> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdialed.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscribe to events

> Auto-trigger a Definition from an internal business event — create an exact-match subscription and emit events from a flow

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`.

<Note>
  **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.
</Note>

## 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`).

<CodeGroup>
  ```bash curl theme={null}
  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"
    }'
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

```json theme={null}
{
  "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"
}
```

<Tip>
  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.
</Tip>

## 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`:

```json theme={null}
{
  "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 (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.

<CodeGroup>
  ```bash curl theme={null}
  # 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"
  ```

  ```javascript JavaScript theme={null}
  // 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 } },
  );
  ```

  ```python Python theme={null}
  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"]},
  )
  ```
</CodeGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Event subscriptions" icon="bell" href="/concepts/event-subscriptions">
    The full object reference, matching rules, and cycle protection.
  </Card>

  <Card title="Catalog" icon="layer-group" href="/concepts/catalog">
    The `getdialed__utils__emit_event` action and everything else you can call from a flow.
  </Card>
</CardGroup>