Event subscriptions

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

{
  "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:

{
  "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.

Cycle protection. The causation chain is threaded through every event-triggered batch. 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.

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`	`/flows/event-subscriptions`	Create an exact-match subscription bound to a definition you own. Returns `201`.
`GET`	`/flows/event-subscriptions`	List your org’s subscriptions with cursor pagination (`cursor`, `limit`), newest first.
`GET`	`/flows/event-subscriptions/{sub_id}`	Fetch one subscription.
`DELETE`	`/flows/event-subscriptions/{sub_id}`	Delete a subscription. Returns `204`. Events after deletion no longer fire; already-fired batches are unaffected.

Creating one:

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

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

Getting Started

Core Concepts

Building Flows

Triggers & Streaming

The event subscription object

Emitting events

The auto-trigger model

Managing subscriptions

Next steps

Subscribe to events

Webhooks

​The event subscription object

​Emitting events

​The auto-trigger model

​Managing subscriptions

​Next steps

Subscribe to events

Webhooks

The event subscription object

Emitting events

The auto-trigger model

Managing subscriptions

Next steps