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

# Event subscriptions

> Auto-trigger flow definitions from internal business events emitted inside your own flows

Event subscriptions auto-trigger [definitions](/concepts/flow-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.

Where [webhooks](/concepts/webhooks) react to *external* POSTs, event subscriptions react to events your own flows raise deliberately — a way to fan one flow's outcome out into others without hard-wiring the caller to the callee.

```json theme={null}
{
  "id": "evsub_9f8e7d6c5b4a",
  "event_type": "list.refreshed",
  "definition_id": "def_a1b2c3d4",
  "enabled": true
}
```

## The event subscription object

| Field           | Type     | Description                                                                              |
| --------------- | -------- | ---------------------------------------------------------------------------------------- |
| `id`            | string   | Subscription identifier (e.g. `evsub_9f8e7d6c5b4a`).                                     |
| `org_id`        | string   | Owning organization — matching is scoped here.                                           |
| `event_type`    | string   | Exact event name to match (min length 1). No wildcards or prefix matching.               |
| `definition_id` | string   | Definition to fire on a match. Must belong to your org and be `active` at dispatch time. |
| `enabled`       | boolean  | `true` fires on match; `false` subscriptions never fire.                                 |
| `created_at`    | datetime | When the subscription was created.                                                       |
| `updated_at`    | datetime | When it was last modified.                                                               |

## Emitting events

Add `getdialed__utils__emit_event` as a task in any definition to raise an event. System and lifecycle events are **not** auto-emitted — emission is always deliberate:

```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`. Defaults to `{}`. |

Emission runs as a durable task inside your worker, so transient delivery failures are covered by the standard retry policy.

## The auto-trigger model

When a task emits an event, the platform matches its `event_type` against every enabled subscription in the same org and fires each matched definition with the event `payload` as `input_data`. One event can fan out to several subscriptions; a definition with no matching subscription simply drops the event.

<Warning>
  **Cycle protection.** The causation chain is threaded through every event-triggered job. If definition A emits an event that triggers B, which emits one that triggers C, the chain's depth is checked before each dispatch — **depth > 5 is rejected** (`CycleDetectedError`), cutting off runaway trigger loops (including A → B → A cycles) at a bounded depth.
</Warning>

## Managing subscriptions

All management endpoints require authentication and operate only on your organization's subscriptions. Mutating endpoints require an admin-role caller (an `X-API-Key` is admin-equivalent).

| Method   | Endpoint                        | Purpose                                                                                                        |
| -------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `POST`   | `/event-subscriptions`          | Create an exact-match subscription bound to a definition you own. Returns `201`.                               |
| `GET`    | `/event-subscriptions`          | List your org's subscriptions with cursor pagination (`cursor`, `limit`), newest first.                        |
| `GET`    | `/event-subscriptions/{sub_id}` | Fetch one subscription.                                                                                        |
| `DELETE` | `/event-subscriptions/{sub_id}` | Delete a subscription. Returns `204`. Events after deletion no longer fire; already-fired jobs are unaffected. |

Creating one:

```bash theme={null}
curl -X POST "$BASE_URL/event-subscriptions" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "list.refreshed",
    "definition_id": "def_a1b2c3d4"
  }'
```

<Note>
  Cross-tenant or missing definitions both return `404` on create — never `403` — so a caller cannot probe another org's definition id space. Binding to a definition that is later deactivated is caught at dispatch time (the definition must be `active` when the event fires).
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Subscribe to events" icon="bell" href="/guides/subscribe-to-events">
    A step-by-step walkthrough: emit an event and wire a subscription to it.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/concepts/webhooks">
    Trigger definitions from external systems instead of internal events.
  </Card>
</CardGroup>